diff --git a/doc/FAQ b/doc/FAQ deleted file mode 100644 index 035811cf6b..0000000000 --- a/doc/FAQ +++ /dev/null @@ -1,1067 +0,0 @@ - Freeciv Frequently Asked Questions (FAQ) - - (from http://www.freeciv.org/wiki/FAQ) - - Contents - - 1 Gameplay - 1.1 OK, so I installed Freeciv. How do I play? - 1.2 How do I play multiplayer? - 1.3 Where is the chatline you are talking about, how do I - chat? - 1.4 Why can't I attack another player's units? - 1.5 How do I declare war on another player? - 1.6 How do I do diplomatic meetings? - 1.7 How do I trade money with other players? - 1.8 How can I change the way a Freeciv game is ended? - 1.9 My irrigated grassland produces only 2 food. Is this a - bug? - 1.10 How do I play against computer players? - 1.11 Can I build up the palace or throne room as in the - commercial Civilization games? - 1.12 Can I build land over sea/transform ocean to land? - 1.13 Can I change settings or rules to get different types of - games? - 1.14 How compatible is Freeciv with the commercial - Civilization games? - 1.15 My opponents seem to be able to play two moves at once! - 1.16 I am far superior to my opponent but their last city is on - a 1x1 island so I cannot conquer it, and they won't give up. - What can I do? - 1.17 Why are the AI players so hard on 'novice' or 'easy'? - 1.18 Why are the AI players so easy on 'hard'? - 1.19 What distinguishes AI players from humans? What do the - skill levels mean? - 1.20 How do I play on a hexagonal grid? - 1.21 How do I create teams of AI or human players? - 1.22 I want more action. - 1.23 I can't see trade routes in the city dialog (GTK+) - 2 Community - 2.1 Does Freeciv violate any rights of the makers of - Civilization I or II? - 2.2 How do I wake up in the morning? - 2.3 Where can I ask questions or send improvements? - 3 Technical Stuff - 3.1 I've found a bug, what should I do? - 3.2 I've started a server but the client cannot find it! - 3.3 I can play on my own server, but the metaserver doesn't - seem to work. - 3.4 How do I change the metaserver info string? - 3.5 Am I using the latest version? Do I need to upgrade? - 3.6 "cannot open display :0" - 3.7 HOME directory not set? - 3.8 How do I restart a saved game? - 3.9 The server cannot save games! - 3.10 Where are the save games located by default? - 3.11 How do I find out about the available units, - improvements, terrain types, and technologies? - 3.12 I hate isometric view! How do I play with Civilization I - style graphics? - 3.13 What other GUI options do I have for the Freeciv client? - 3.14 How do I enable/disable sound support? - 3.15 Where can I find more information on the *.ruleset files? - 3.16 How can I add additional civilizations in the nation/ - subdirectory, or add cities to the list for an existing - nation? - 3.17 How can I change the language of my client/server? - 3.18 How do I get the latest development code? - 3.19 What are the system requirements? - 4 Windows - 4.1 How do I use Freeciv under MS Windows? - 4.2 OK, I've downloaded and installed it, how do I run it? - 4.3 I've started the Freeciv client, but don't know what to do - next? - 4.4 How do I use a different tileset? - 4.5 How do I use a different ruleset? - 4.6 I opened a ruleset file in Notepad and it is very hard to - read - 5 Mac OS X - -------- - -1 Gameplay - -------- - -1.1 OK, so I installed Freeciv. How do I play? - - Start the client. Depending on your system, you might choose it from a - menu, double-click on the freeciv-gtk3 executable program, or type - freeciv-gtk3 in a terminal (to start the default "gtk3" client). - - Once the client starts, to begin a single-player game, select Start new - game. Now edit your game settings (the defaults should be fine for a - beginner-level single-player game) and press the Start button. - - (Freeciv is a client/server system. But in most cases you don't have to - worry about this; the client starts a server automatically for you when - you start a new game.) - - Once the game is started you can find information in its Help menu. If - you've never played a Civilization-style game before you may want to - look at the help on Strategy and Tactics. - - You can continue to change the game settings through the Remote Server - menu item in the Options submenu of the Game menu. Type /help in the - chatline (or server command line) to get more information about server - commands. - - Detailed explanations of how to play Freeciv are also in the - ./doc/README file distributed with the source code, and in the in-game - help. - -------- - -1.2 How do I play multiplayer? - - You can either join a network game run by someone else, or host your - own. - - To join a network game, choose Connect to Network Game and then - Internet Metaserver. A list of active servers should come up; - double-click one to join it. (The Freeciv project does not currently - run any game servers, so any servers you find are likely to be run by - third parties who have decided to advertise them.) - - You can also choose to directly connect to a specific server (including - ones not on the metaserver list), provided you know the IP address and - port of the server you're connecting to. This server will then show up - under Local Area Network. - - To host your own game, we recommend starting a separate server by hand. - (As of 2.4.0, it's no longer possible to host a network game from the - client; in any case, we didn't recommend it, as if the client crashed - or quit, the server and hence the game would be lost.) - - To start the server, enter freeciv21-server in a terminal or by - double-clicking on the executable. This will start up a text-based - interface. - - If all players are on the same LAN, they should launch their clients, - choose Connect to Network Game and then Local Area Network. You should - see the existing server listed; double-click on it to join. - - To play over the Internet, players will need to enter the hostname and - port into their clients, so the host will need to tell the other - players those details. You may also start up the server with the -m - command-line option to make it report to the Metaserver and allow other - players to connect to it through the Internet Metaserver tab. - - Note that hosting an Internet server from a home Internet connection is - often problematic, due to firewalling and NAT that can make the server - unreachable from the wider Internet. The metaserver does not currently - check that a server is reachable before publishing it, so unfortunately - it is entirely possible to publish the existence of a game that no-one - will be able to connect to. Safely bypassing NAT and firewalls is - beyond the scope of this FAQ. - -------- - -1.3 Where is the chatline you are talking about, how do I chat? - - The chatline is located at the bottom of the window. Sometimes you have - to activate a Chat tab to see it. - - In the Gtk client, a shortcut to reach the chatline is the apostrophe - (') key. In the SDL client you have to press Tab to access the - chatline. - - The chatline can be used for normal chatting, or for issuing server - commands by typing a forward-slash '/' followed by the server command. - -------- - -1.4 Why can't I attack another player's units? - - You have to declare war first. See section for How do I declare war on - another player below. - - (As a note, you start out at war with all players; at lower skill - levels, AI players offer you a cease-fire treaty upon first contact, - which if accepted has to be broken before you can attack the player's - units or cities.) - -------- - -1.5 How do I declare war on another player? - - Go to the Nations report, select the player, then choose Cancel Treaty - from the bottom-located Diplomacy menu. This drops you from "cease - fire", "armistice", or "peace" into "war". If you've already signed a - permanent "alliance" treaty with the player, you will have to cancel - treaties several times to get to "war". - - See the in-game help on Diplomacy for more detail. - -------- - -1.6 How do I do diplomatic meetings? - - Go to the Nations report, select a player, then choose Meet from the - bottom-located Diplomacy menu. But remember that you have to either - have contact with the player or an embassy established in one of their - cities. - -------- - -1.7 How do I trade money with other players? - - If you want to make a monetary exchange, first initiate a diplomatic - meeting as described in the section about How do I do diplomatic - meetings above. In the diplomacy dialog, enter the amount you wish to - give in the gold input field on your side or the amount you wish to - receive in the gold input field on their side. With the focus in either - input field, press Enter to insert the clause into the treaty. - -------- - -1.8 How can I change the way a Freeciv game is ended? - - A standard Freeciv game ends when only allied players/teams are left - alive, when a player's spaceship arrives at Alpha Centauri, or when you - reach the ending turn - whichever comes first. - - You can change the default ending turn by changing the endturn setting. - You can do this through Remote Server (see article on Server options) - under the Options menu item in the Game menu or by typing into the - chatline something like: -/set endturn 300 - - You can end a running game immediately with: -/endgame - - For more information, try: -/help endgame - - If you want to avoid the game ending by space race, or require a single - player/team to win, you can change the victories setting - again either - through the Server Options dialog or through the chatline. For instance - this changes from the default setting spacerace|allied to disallow - allied victory and space race: -/set victories "" - - You can instead allow space races without them ending the game by - instead changing the endspaceship setting. - - A single player who defeats all enemies will always win the game -- - this conquest victory condition cannot be changed. - - In rulesets which support it, a cultural domination victory can be - enabled, again with the victories setting. - -------- - -1.9 My irrigated grassland produces only 2 food. Is this a bug? - - No, it isn't. It's a feature. Your government is probably despotism, - which has a -1 output whenever a tile produces more than 2 units of - food/production/trade. You should change your government (see - Government) to get rid of this penalty. - -------- - -1.10 How do I play against computer players? - - See also the How do I create teams of AI or human players? section - below. - - In most cases when you start a single-player game you can change the - number of players, and their difficulty, directly through the - spinbutton. Note the number of players here includes human players (an - aifill of 5 adds AI players until the total number of players becomes - 5). - - If you are playing on a remote server, you'll have to do this manually. - Change the aifill server option through the Remote Server options - dialog, or do it on the chatline with something like: -/set aifill 30 - - Difficulty levels are set with the /cheating, /hard, /normal, /easy, - /novice, and /handicapped commands. - - You may also create AI players individually. For instance, to create - one hard and one easy AI player, enter: -/create ai1 -/hard ai1 -/create ai2 -/easy ai2 -/list - - More details are in the ./doc/README file supplied with Freeciv and the - online manual on this site. - -------- - -1.11 Can I build up the palace or throne room as in the commercial Civilization -games? - - No. This feature is not present in Freeciv, and will not be until - someone draws the graphics for it. - -------- - -1.12 Can I build land over sea/transform ocean to land? - - Yes. You can do that by placing engineer units on a transport and going - to the ocean tile you want to build land on (this must be in a land - corner). Click the transport to display a list of the transported - engineers and activate them. Then give them the order of transforming - this tile to swamp. This will take a very long time though, so you'd - better try with 6 engineers at a time. There must be 3 adjacent land - tiles to the ocean tile you are transforming. - -------- - -1.13 Can I change settings or rules to get different types of games? - - Of course. - - Before the game is started, you may change settings through the server - options dialog (available in the pregame screen). You may also change - these settings or use server commands through the chatline. If you use - the chatline, use the -/show - - command to display the most commonly-changed settings (see article on - show), or -/help - - to get help on a particular setting, or -/set - - to change a setting to a particular value (see article on server - options). After the game begins you may still change some settings (but - not others). - - World maps can be created using the built-in map editor in the GTK - clients. It is also possible to edit running games: Just enable Editing - Mode from the Edit menu. (You may also unzip and edit any savegame with - a text editor, if you're ambitious, although the format is not - documented and is subject to change.) - - You can create rulesets or "modpacks" - alternative sets of units, - buildings, and technologies. Several different rulesets come with the - Freeciv distribution, including a civ1 (Civilization 1 compatibility - mode), and civ2 (Civilization 2 compatibility mode). Use the rulesetdir - command (see rulesetdir) to change the ruleset (as in /rulesetdir - civ2). Note the ruleset mechanism is still being refined from version - to version. In the GTK client you are able to choose the ruleset from a - dropdown on the pregame screen. - - Finally, upgrade! Freeciv continues to improve from version to version: - a rule may change when the mailing list agrees it is 'wrong'. See, for - instance, the NEWS. - -------- - -1.14 How compatible is Freeciv with the commercial Civilization games? - - Freeciv was created as a multiplayer version of Civilization™ with - players moving simultaneously. Rules and elements of Civilization II, - and features required for single-player use, such as AI players, were - added later. - - This is why Freeciv comes with several game configurations (rulesets): - the civ1 and civ2 rulesets implement game rules, elements and features - that bring it as close as possible to Civilization I and Civilization - II respectively, while other rulesets such as the default classic - ruleset tries to reflect the most popular settings among Freeciv - players. Unimplemented Civilization I and II features are mainly those - that would have little or no benefit in multiplayer mode, and nobody is - working on closing this gap. - - Little or no work is being done on implementing features from other - similar games, such as SMAC, CTP or Civilization III. - - So the goal of compatibility is mainly used as a limiting factor in - development: when a new feature is added to Freeciv that makes gameplay - different, it is generally implemented in such a way that the - "traditional" behaviour remains available as an option. However, we're - not aiming for absolute 100% compatibility; in particular, we're not - aiming for bug-compatibility. - - See also Projects. - -------- - -1.15 My opponents seem to be able to play two moves at once! - - Freeciv's multiplayer facilities are asynchronous: during a turn, moves - from connected clients are processed in the order they are received. - Server managed movement is executed in between turns. This allows human - players to surprise their opponents by clever use of goto or quick - fingers. - - Server settings to mitigate this problem include: - * phasemode, which has an alternating movement mode, in which only - one player can move their units at a time. - * timeaddenemymove (which extends the turn timeout when an enemy's - unit is seen moving). - * (since 2.3.x) unitwaittime (which imposes a minimum time between - moves of a single unit on successive turns). - -------- - -1.16 I am far superior to my opponent but their last city is on a 1x1 island so -I cannot conquer it, and they won't give up. What can I do? - - Research 'amphibious warfare', build a marine, and get them. - Alternatively research 'combined arms' and either move a helicopter or - airdrop a paratroopers unit there. - - If you can't build marines yet, but you do have engineers, and other - land is close-by, you can also build a land-bridge to the island (i.e. - transform the ocean). - -------- - -1.17 Why are the AI players so hard on 'novice' or 'easy'? - - You are not expanding fast enough. Read the How to Play article for - some general tips how to get a head start in the game. - - You can also turn off Fog of War. That way, you will see the attacks of - the AI. Just type '/set fogofwar disabled' on the chat line before the - game starts. - -------- - -1.18 Why are the AI players so easy on 'hard'? - - Several reasons. For example, the AI is heavily playtested under and - customized to the default ruleset and server settings. Although there - are several provisions in the code to adapt to changing rules, playing - under different conditions is quite a handicap for it. Though mostly - the AI simply doesn't have a good, all encompassing strategy besides - "eliminate nation x". For further details, see the article on AI. - - To make the game harder, you could try putting some or all of the AI - into a team. This will ensure that they will waste no time and - resources negotiating with each other and spend them trying to - eliminate you. They will also help each other by trading techs. See the - question How do I create teams of AI or human players? - - You can also form more than one AI team by using any of the different - predefined teams, or put some AI players teamed with you. - -------- - -1.19 What distinguishes AI players from humans? What do the skill levels mean? - - AI players in Freeciv operate in the server, partly before all clients - move, partly afterwards. Unlike the clients, they can in principle - observe the full state of the game, including everything about other - players, although most levels deliberately restrict what they look at - to some extent. - - All AI players can change production without penalty. Some levels - (generally the harder ones) get other exceptions from game rules; - conversely, easier levels get some penalties, and deliberately play - less well in some regards. - - For more details about how the skill levels differ from each other, see - the help for the relevant server command (for instance /help hard). - - Other than as noted here, the AI players are not known to cheat. - -------- - -1.20 How do I play on a hexagonal grid? - - It is possible to play with hexagonal instead of rectangular tiles. To - do this you need to set your topology before the game starts; set this - with Map topology index from the game settings, or in the chatline: -/set topology hex|iso|wrapx - - This will cause the client to use an isometric hexagonal tileset when - the game starts (go to Game > Options >Local options to choose a - different one from the drop-down; hexemplio and isophex are included - with the game). - - You may also play with overhead hexagonal, in which case you want to - set the topology setting to 'hex|wrapx'; the hex2t tileset is supplied - for this mode. - -------- - -1.21 How do I create teams of AI or human players? - - The GTK and Qt clients have a GUI for setting up teams - just right - click on any player and assign them to any team. - - You may also use the command-line interface (through the chatline.) - - First of all try the /list command. This will show you all players - created, including human players and AI players (both created - automatically by aifill or manually with /create). - - Now, you're ready to assign players to teams. To do this you use the - team command. For example, if there's one human player and you want two - more AI players on the same team, you can do to create two AI players - and put them on the same team you can do -/set aifill 2 -/team AI*2 1 -/team AI*3 1 - - You may also assign teams for human players, of course. If in doubt use - the /list command again; it will show you the name of the team each - player is on. Make sure you double-check the teams before starting the - game; you can't change teams after the game has started. - -------- - -1.22 I want more action. - - In Freeciv, expansion is everything, even more so than in the - single-player commercial Civilization games. Some players find it very - tedious to build on an empire for hours and hours without even meeting - an enemy. - - There are various techniques to speed up the game. The best idea is to - reduce the time and space allowed for expansion as much as possible. - One idea for multiplayer mode is to add AI players: they reduce the - space per player further, and you can toy around with them early on - without other humans being aware of it. This only works after you can - beat the AI, of course. - - Another idea is to create starting situations in which the players are - already fully developed. There is no automated support for this yet, - but you can create populated maps with the built-in editor. - -------- - -1.23 I can't see trade routes in the city dialog (GTK+) - - In the GTK client, you can see the effect of trade routes by left - clicking and holding on the trade value in the Info panel of the city - dialog. - -------- - -2 Community - -------- - -2.1 Does Freeciv violate any rights of the makers of Civilization I or II? - - There have been debates on this in the past and the honest answer seems - to be: We don't know. - - Freeciv doesn't contain any actual material from the commercial - Civilization games. (The Freeciv maintainers have always been very - strict in ensuring that materials contributed to the Freeciv - distribution or website do not violate anyone's copyright.) The name of - Freeciv is probably not a trademark infringement. The user interface is - similar, but with many (deliberate) differences. The game itself can be - configured to be practically identical to Civilization I or II, so if - the rules of a game are patentable, and those of the said games are - patented, then Freeciv may infringe on that patent, but we don't - believe this to be the case. - - Incidentally, there are good reasons to assume that Freeciv doesn't - harm the sales of any of the commercial Civilization games in any way. - -------- - -2.2 How do I wake up in the morning? - - We're open to suggestions on this one. - - You can try to give Freeciv to your boss. There is no guarantee, but he - may wake up later than you. Remind yourself that if you run into him at - Civilization Anonymous, it's time to change jobs. - -------- - -2.3 Where can I ask questions or send improvements? - - Please ask questions about the game, its installation, or the rest of - this site at the Freeciv Forums. - - Patches and bug reports are best reported to the Freeciv bug tracking - system at https://www.hostedredmine.com/projects/freeciv. - -------- - -3 Technical Stuff - -------- - -3.1 I've found a bug, what should I do? - - See the article on Bug Reporting. - -------- - -3.2 I've started a server but the client cannot find it! - - By default, your server will be available on host localhost (your own - machine), port 5556; these are the default values your client uses when - asking which game you want to connect to. - - So if you don't get a connection with these values, your server isn't - running, or you used -p to start it on a different port, or your - system's network configuration is broken. - - To start your local server, run freeciv21-server. Then type start at the - server prompt to begin! -mike@localhost:/usr/local/bin$ ./freeciv21-server -This is the server for Freeciv version 2.6.0 -You can learn a lot about Freeciv at http://www.freeciv.org/ -2: Loading rulesets. -2: AI*1 has been added as Easy level AI-controlled player (classic). -2: AI*2 has been added as Easy level AI-controlled player (classic). -2: AI*3 has been added as Easy level AI-controlled player (classic). -2: AI*4 has been added as Easy level AI-controlled player (classic). -2: AI*5 has been added as Easy level AI-controlled player (classic). -2: Now accepting new client connections on port 5556. - -For introductory help, type 'help'. -> start -Starting game. - - If the server is not running, you will NOT be able to connect to your - local server. - - If you can't connect to any of the other games listed, e.g. those on - the metaserver, a firewall in your organization/ISP is probably - blocking the connection. - - If you are running a personal firewall, make sure that you allow - communication for freeciv21-server and the Freeciv client to the trusted - zone. If you want to allow others to play on your server, allow - freeciv21-server to act as a server on the Internet zone. - -------- - -3.3 I can play on my own server, but the metaserver doesn't seem to work. - - If your Metaserver tab turns up an empty list, there might something - wrong with your setup. - - First, check your Freeciv version. Freeciv clients can only talk to - servers of the same major version (2.6.x can only talk to 2.6.y), and - there may simply be no public servers for the version you're running. - Check out the web interface (which shows servers for all versions) and - look at the "version" column. - - If you can view the metaserver page with your web browser, and servers - are listed, but the client's Metaserver tab still fails to list them, - you may be behind a non-transparent proxy. See article on proxy - settings for a detailed explanation. - -------- - -3.4 How do I change the metaserver info string? - - Use the /metamessage command. See /help metamessage. - -------- - -3.5 Am I using the latest version? Do I need to upgrade? - - The current stable Freeciv version is 2.6.0. For an overview of - changes that went into this release, see the NEWS-2.6.0 article. - - The NEWS-#.#.# article is only updated for a new release; updates to - Git can be reviewed in the online source code browser. - - If you decide to upgrade, see the Download page for source code or - contributed binaries. If you have a working client, and you don't know - its version, start it, load a game or scenario, or just start a new - game, click on Help for the help menu, and on About Freeciv to see the - version and the client type (GTK2, GTK3, QT, SDL2, …). - - It's possible that not all precompiled binaries and ports have been - updated to 2.6.0 yet. If you can contribute, please do! Prepare a - package and announce it to freeciv-dev@freelists.org. - - Clients and servers of different major versions are generally - incompatible due to changes in the client/server protocol. You will see - incompatibilities as a 'mismatched capabilities' error. Different minor - versions should be compatible, however. For example, 2.5.4 and 2.5.0 - are compatible; 2.5.4 and 2.6.0 are not. - -------- - -3.6 "cannot open display :0" - - The Freeciv client is unable to open a window on your local X display. - Are you running an X server at all? Maybe you need to install and run - one, or switch to a Freeciv client that doesn't need X; see the - previous question. - - Under Mac OS X, try starting the Freeciv client from the xterm session - running under X. - -------- - -3.7 HOME directory not set? - - The Freeciv client wants to write a configuration file named - freeciv-client-rc-2.6 (for Freeciv 2.6.x) in a directory called - .freeciv in your $HOME directory. On Windows the %HOME%-directory can - be either explicitly set, or defaults to %APPDATA%. So for instance for - Freeciv 2.6 the Windows clients might put their common configuration - file in - C:\Users\username\AppData\Roaming\.freeciv\freeciv-client-rc-2.6. - -------- - -3.8 How do I restart a saved game? - - If for some reason you can't use the start-screen interface for loading - a game, you can load one directly through the client or server command - line (see Command-line options). You can start a client such as - freeciv-gtk3, or freeciv21-server, with the -f option, for example: -freeciv21-server -f freeciv-T0175-Y01250-auto.sav.bz2 - - Or you can use the /load command inside the server before starting the - game. - -------- - -3.9 The server cannot save games! - - In a local game started from the client, the games will be saved into - the default Freeciv save directory (typically ~/.freeciv/saves/). If - you are running the server from the command line, however, any - savegames will be stored in the current directory. If the autosaves - server setting is set appropriately, the server will periodically save - the game automatically (which can take a lot of disk space in some - cases); the frequency is controlled by the saveturns setting. In any - case, you should check the ownership, permissions, and disk space/quota - for the directory or partition you're trying to save to. - -------- - -3.10 Where are the save games located by default? - - On Unix like systems, they will be in ~/.freeciv/saves. On Windows, - they are typically found in a directory like - C:\Users\username\AppData\Roaming\.freeciv\saves. - - You could change this by setting the HOME environment variable, or - using the --saves command line argument to the server (you would have - to run it separately). - -------- - -3.11 How do I find out about the available units, improvements, terrain -types, and technologies? - - There is extensive help on this in the Help menu, but only once the - game has been started - this is because all of these things are - configurable up to that point. (Some work needs to be done to make this - more intuitive.) - - The game comes with an interactive tutorial scenario. To run it, select - Start Scenario Game from the main menu, then load the tutorial - scenario. - - Outside the Freeciv client, we have some online tutorials in the Docs - section of the wiki. A graph of the (default) technology tree is - available on the wiki. - -------- - -3.12 I hate isometric view! How do I play with Civilization I style graphics? - - When starting the game, go to More Game Options > Geological > Map - topology index, and make sure Isometric is not checked. - - The overhead tileset trident is supplied for this topology. - -------- - -3.13 What other GUI options do I have for the Freeciv client? - - The look and feel of your GUI is mainly determined by the Freeciv - client you use. - - The recommended client is the Gtk client. There are a range of - different Gtk clients for different versions of the Gtk - library—Gtk2/3/etc—but they all support more or less the same feature - set. If in doubt, pick the Gtk3 client. - - The Qt client is a newer client using the Qt toolkit. It has a more - immersive interface. It supports most features, with the notable - exception of the map editor. - - The SDL clients provide a more immersive experience, but lags behind - somewhat in features. (Again, there are two versions of this for - different versions of the SDL library.) - - The original client was based on the Athena widget set (Xaw), which is - fast and was at the time more widely available, but it is no longer - maintained, is buggy, and lacks features; it will be removed in a - future release. This client can also be compiled to use Xaw3d. - - All of these clients should compile and run on any Unix variant we are - aware of, not just the ones for which our download section provides - native installation support. - - For Windows, the Gtk and Qt clients are recommended. - - Some details of the GUI can be configured from the running client. - - A larger impact is made by the tileset used to display terrain, cities, - units, etcetera. Freeciv comes with some tilesets for all topologies; - some more can be acquired with the freeciv-modpack utility. - - We do not distribute commercial Civilization™ game tiles for obvious - copyright reasons. - -------- - -3.14 How do I enable/disable sound support? - - The client can be started without sound by supplying the commandline - arguments: -P none. The default sound plugin can also be configured in - the client settings. - - If the client was compiled with sound support, it will be enabled by - default. (The only sound plugin supported currently is sdl.) - - Further instructions are in ./doc/README.sound in the source tarball. - - If sound does not work, try: -freeciv-gtk3 -d 3 -P -S stdsounds - - This will help you get some debug information, which might give a clue - why the sound does not work. - -------- - -3.15 Where can I find more information on the *.ruleset files? - - There is some documentation in the ./doc/ directory, such as - ./doc/README.effects. The supplied ruleset files also have a minimal - explanation of what all the fields mean, so classic/buildings.ruleset - would for instance list the meaning of the fields in the - buildings.ruleset. Also of interest might be the rulesets page on - freeciv.org. - -------- - -3.16 How can I add additional civilizations in the nation/ subdirectory, -or add cities to the list for an existing nation? - - See the Nations article or ./doc/README.nations in the source tarball. - -------- - -3.17 How can I change the language of my client/server? - - See the Interface Language wiki article. - -------- - -3.18 How do I get the latest development code? - - Use Git directly: - 1. Obtain and install Git on your Unix machine. On modern - distributions it is already there; look for the git command. You - can get Git from git-scm.com. - 2. Grab the source: - - $ git clone https://github.com/freeciv/freeciv - - Once you're retrieved the source, to update it, cd into the freeciv - directory and issue git pull. - - Another useful git command is git diff. - - This shows the changes between the version you have on disk and the - current development code. - - This is development code; it may contain new features, bugs, and - incompatibilities with older versions. - - See also How to Contribute to Freeciv development. - -------- - -3.19 What are the system requirements? - - Memory - - In a typical game the server takes about 30MB of memory and the client - needs about 200MB. These values may change with larger maps or - tilesets. For a single player game you need to run both the client and - the server. - - Processor - - We recommend at least a 200MHz processor. The server is almost entirely - single-threaded, so more cores will not help. If you find your game - running too slow, these may be the reasons: - - Too little memory - Swapping memory pages on disc (virtual memory) is really - slow. Look at the memory requirements above. - - Large map - Larger map doesn't necessary mean a more challenging or - enjoyable game. You may try a smaller map. - - Many AI players - Again, having more players doesn't necessary mean a more - challenging or enjoyable game. - - City Governor (CMA) - This is a really useful client side agent which helps you - to organize our citizens. However, it consumes many CPU - cycles. - - Maps and compression - Creating map images and/or the compression of saved games - for each turn will slow down new turns. Consider using no - compression. - - Graphic display - - The GTK client works well on 1024x800 or higher resolutions. On smaller - screens you may want to enable the Arrange widgets for small displays - option under Interface tab in local options. - - Network - - A 56Kb modem should be enough to play a typical online game. However, - many players suggest that a large ping is a big disadvantage. Your ISP - mustn't block ports 5556 - 5600, because these are the ports which - typical servers are run on. - -------- - -4 Windows - -------- - -4.1 How do I use Freeciv under MS Windows? - - Precompiled binaries can be downloaded from www.freeciv.org. The native - Windows packages come as self-extracting installers. - - Simply download and install one of the .EXE installers (GTK, SDL, or - QT). All versions require Windows 7 or later. - -------- - -4.2 OK, I've downloaded and installed it, how do I run it? - - If you used one of the self installer versions then there's a program - group with the name chosen at installation time (for example, - Freeciv 2.6.0 (GTK+3 client).) Just go to click on - Start→Programs→Freeciv 2.6.0 (GTK+3 client)→Freeciv - - That's it! You should be up and running. - -------- - -4.3 I've started the Freeciv client, but don't know what to do next? - - The following steps should get you started: - 1. The Freeciv client will pop up and after a second you will be taken - to the main menu. - 2. If you want to play against other humans (I think they're human - anyway :-) then click on the Connect to Network Game button in the - main menu. Then either type in the IP address of the server or - select the Internet Metaserver tab to play on online public - servers. Then select an available game and click the Connect - button. (You may need to click the Update button to get the list of - servers initially and to update it after a while.) - 3. If you want to play on your local machine against the AI (all other - players are AI controlled) then click on the Start New Game button. - Then select your difficulty level and the Total players (it - includes yourself, so if you wanted to play against four AI - players, you'd select 5). - 4. Click the Pick Nation button to choose your nation, leader name, - sex, and city style. - 5. Click the Start button. - - That's it! Enjoy! - -------- - -4.4 How do I use a different tileset? - - If the tilesets supplied with Freeciv don't do it for you, some popular - add-on tilesets are available through the "Freeciv Modpack Installer" - utility. To install these, just launch the installer from the Start - menu, and choose the one you want; it should then be automatically - downloaded and made available for the current user. - - If the tileset you want is not available via the modpack installer, - you'll have to install it by hand from somewhere. - - Then you have to unpack the tileset into the appropriate place. It's - best to install it in your user directory. Locate the existing client - settings file freeciv-client-rc-2.6; see the question HOME directory - not set? to see where that might be. You want to put the tileset in a - subdirectory named after the current version (e.g., 2.6\) in the same - place as the client settings file. Usually, the main tilespec file - foo.tilespec goes directly under 2.6\, and the rest of the tileset - files will go in a subdirectory named after the tileset (e.g., - 2.6\foo). - - You can alternatively unpack the tileset into the same data directory - as the rest of your Freeciv installation, alongside the supplied - .tilespec files, but that can lead to trouble with uninstallation or - upgrades. - - Once the tileset is installed, you should be able to select it in the - topology-specific tileset dropdowns in the client options. You will - need to make sure your game uses the appropriate map topology for the - tileset in the game options. - - You can also pass a command-line argument to the Freeciv client when - you start it to force use of a specific tileset. This also requires - that the tileset has been installed in a correct place. Open a Command - Prompt, find the client executable, and start the client with the - --tiles tilesetname option. For example for the gtk3 client, you might - start -freeciv-gtk3 --tiles hexemplio - -------- - -4.5 How do I use a different ruleset? - - Again, this is easiest if the ruleset is available through the "Freeciv - Modpack Installer" utility that's shipped with Freeciv. - - Otherwise, a different ruleset can be used by downloading the ruleset - and extracting it in the same place as you would a tileset (see - previous question). Generally, the .ruleset and .lua files go in a - subdirectory named after the ruleset (for instance ancients\*.ruleset; - if there is a .serv file it generally goes directly in the 2.6\ - directory. - - Then you need to tell Freeciv to use it. For single-player games, if - there is a .serv file, the ruleset should be available to select from - the drop-down in the client. Otherwise, you can load a ruleset which - has a foo.serv file with -/read foo - - from the client chatline or server command line before starting the - game; you can read a ruleset without a .serv file by typing -/rulesetdir ''ruleset directory'' - -------- - -4.6 I opened a ruleset file in Notepad and it is very hard to read - - The ruleset files (and other configuration files) are stored with UNIX - line endings which Notepad doesn't handle correctly. Please use an - alternative editor like WordPad, notepad2, or notepad++ instead. - -------- - -5 Mac OS X - - None of the current development team use the Mac OS. We're no longer - building official packages, and don't have recent experience. - - There are unofficial installer packages available; see the - Install-MacOSX article on the Freeciv wiki for links and more - information. diff --git a/doc/HOWTOPLAY b/doc/HOWTOPLAY deleted file mode 100644 index 3527df5032..0000000000 --- a/doc/HOWTOPLAY +++ /dev/null @@ -1,273 +0,0 @@ -The Freeciv playing HOWTO - - Originally by Michael Hohensee (aka Zarchon) - - -If you're looking for how to install Freeciv, look in INSTALL. -If you're looking for how to get Freeciv running, look in README. - -If you have never played the Civilization games, it's easiest to -start by reading the Freeciv Manual, available separately at: - - http://www.freeciv.org/wiki/Manual - -If you're looking for ideas on playing Freeciv, then keep reading!! - - Now that you have Freeciv running, you'll want to play your -first few games. It is recommended that you try playing solitaire a -few times, so that you can get a feel for how things work, but this is -not necessary. You can also learn by playing with others or against -the AI. - -Q: Can you give me a basic strategy? - - First of all, this isn't a *perfect* strategy; it's not -even a very good one. But it will get you started playing Freeciv. -Part of the appeal of Freeciv is in developing new strategies. - - The game is divided into several stages: - - The Initial Expansion phase - Technological sub-phase - The Second Expansion phase - The Production phase - and The Utter Annihilation of Your Enemies phase - -Initial Expansion: - - This phase is the most critical. The first thing you want to -do is build cities and explore your island. You want lots of cities, -seven or eight at the least. - - The name of the game is to tie down as many squares of land as -possible. When building a city, make sure that you don't overlap too -much with territory from one of your other cities. You can see which -squares are being used by a city by clicking on it. The map of the -city and the surrounding area contains that city's territory. Keeping -this in mind, try to keep your cities fairly close together. The -further apart they are, the more difficult they are to defend and -administer at this stage. (Tip: Try to build on horses or near fish.) - - Now that you have a city or two, you'll want to set the science -rate as high as your government type will allow. Don't worry about -the tax rate, since you won't be building any improvements to drain -your cash; you'll be building settlers. Every city should be churning -out settlers. The more settlers you make, the more cities you can -have; the more cities you have, the faster you gain tech; the faster -you gain tech, the faster you win. After you have built as many -cities as your corner of the world will hold, turn the settlers to -irrigating and building roads. - -(Note: If the food surplus in a city drops to +1 from supporting -too many settlers, and you can't rearrange people to increase it, then -switch them to building temples. Unless you make contact with another -player, don't worry about building military units just yet.) - - All this time, you have been gaining techs as fast as -possible. What you should be shooting for is first "The Republic", -then "Democracy", then "Railroad", and then "Industrialization". -(Some people go for Monarchy before The Republic). As soon as -you've researched a new government type, start a revolution and change -over to it. Cities operate much better as Republics than they do -under Despotism, but note that it's much harder to keep military -units outside of city limits under a Republic. Also, don't forget to -recheck your rates after you've changed governments, as the maximums -vary for each type. - - When you get Democracy, you are equipped to go into the Second -Expansion phase. This is accomplished by changing the government to a -Democracy, making all cities build temples, and setting the luxury -rate to 100%. When you do this, all cities will immediately begin -celebrating, and will grow at a rate of one per turn as long as -there is surplus food. When they've gotten big enough, set the luxury -down to a reasonable level of 20-40%. This places you in the Second -Expansion phase. - - The down-side to this is that setting luxury to 100% means -that your science research will all but stop. After your cities have -grown, and you put science back up to 50% or so, you will again gain -techs, but at a slightly slower rate. If you have done some -exploring, and are not immediately threatened by another player, it -can be a good idea to keep science at maximum until techs start to -take too long to generate. - -Second Expansion Phase: - - When you get your cities to a good sized population, wean them -off luxuries gradually and increase taxes. Once they're down to 30% -luxury or so, put as much of the taxes as you can into science, while -maintaining a positive income. When you get railroad, turn all your -roads into rails, or at least the squares used for production, or -those that form part of a transport network. (Tip: turn every square -used by a city into a road/rail, it increases that city's output. -There's no need to upgrade the very centre square - that's done -automatically). - - Now is the time to develop industrialization, and military -technologies. You should also begin building cities on other islands, -and do some serious exploring if you have not already done so. You -need to find out where your enemies are. Go for techs good for ships, -and try to build Magellan's Expedition. When you feel ready, go into: - -Production Phase: - - Now you're building factories and power plants in your cities. -You want to get as much production as possible out of each city. -Pollution becomes a problem. As soon as you can, try to research Mass -Production for Mass Transits, and Recycling so you can build -Recycling Centers. Once you've got all your cities going strong, you -must build military units. (Note: If you come into contact with -another player, you should immediately build a few attack units, and -at least one defense unit per city.) - - When you want to begin thinking about attacking someone, set -science to 0%, and put raise taxes as high as you can without -provoking disorder. Remember, money can build units too! - - -Utter Annihilation of Your Enemies Phase: - - This can happen at any time, but it's more fun with the -advanced weapons. - - Pick a relatively weak enemy, and send over a few ship-loads of -troops. Take over his cities, and use them to build more units to -take out the rest of them with. Show no quarter! To the death! - -Repeat as often as necessary! ;-) - -[Note for pacifists: Freeciv also allows a player to win by building -and launching a spaceship which arrives at Alpha Centauri before anyone -else.] - - -Additional questions: - -Q. What other strategies are there? - - There are a number of tutorials and strategy guides available at -the Freeciv wiki: - - http://www.freeciv.org/wiki/Tutorials - -Plus, the Freeciv online help describes another strategy. - - -Q. In multiplayer games, what timeout should I set? - - That depends upon the number of players. If there are just -two of you playing, you can usually get away with using timeout 0. If -there are more than two, or if one of the two is going to be away from -his terminal at random intervals and you don't want to halt play, a -timeout of 60 seconds is usually sufficient. Later in the game, -however, as things get more complex, you may want to extend the -timeout to 240 seconds. In general, the more players you have, the -longer a timeout you will need. Feel free to set whatever timeout -seems comfortable, but remember that going above 300 will tend to -bother people. - - -Q. What size map should I use? - - The map size depends upon how many players there are, and how -fast you want the game to end. The default map size (80x50) is big -enough for a fairly quick two player game, but will result in a *very* -fast game if any more than three people are participating. - - Fast games tend to be frustrating for everyone but the winner, -as nobody has really had any time to develop any defense. If you have -more than three people playing, you should use an 80x80 map. If you -have five or more people, you probably want to consider one that's -100x100. - - -Q. What is that "generator" option? - - It alters the map generation process. If you play Freeciv -a few times without changing this setting, you are sure to hear of (or -experience) the horrors of a tiny island. Tiny Island Syndrome (TIS) -is known to make people go insane. To fix this, our kind and loving -coders installed the generator option. -- When set to RANDOM, it creates the map using a random height generator, - with islands of different (and potentially unfair) sizes. -- When set to FRACTAL it generates the map using a pseudo fractal height - generator. This means that the mountains and the hills will be - placed according to everlasting mathematical figures. -- ISLAND generates islands of equal size (sometimes with some smaller - islands thrown in). This way, nobody can whine about losing "on - account of that d**ned island." -- SCENARIO is used for premade maps. (Load a map by typing in - /load /dir/savegame.sav.gz in the input field at the bottom of the - screen, in this way it is possible to change the settings of a game. - Use the map editor to change a map.) -- FAIR is the most fair of all generators for the multiplayer games. - It gives all users or teams identical islands. -- FRACTURE generates maps from a fracture pattern. It tends to place - hills and mountains along the edges of the continents. - -Below the generator option there is the startpos option. This setting -determines how many players are placed on the same continent. Each -generator option has its own default startpos value. Which is loaded -when startpos is DEFAULT. (The default startpos for the fractal height -generator is ALL, which means that the generator will try to place all -the players on the same continent. - -Q. Should I make the game easier by increasing the starting gold? - - If you are inexperienced, and are playing with inexperienced -people, probably no one will object to an increase in the amount of -gold they start with. This is, however, not a good way to learn how -to play. Starting out with lots of money makes the game much easier, -and makes it more difficult for you to learn how to cope with the -default amount. Most experienced players don't increase this setting, -and if they know how to cope with it and you don't, you are going to -go the way of Atlantis. - -Note: The same thing applied to the "techlevel" and "researchspeed" -settings. - - -Q. What about those other settings? - - The rest of them mainly have to do with what sort of world -will be generated and game mechanics. Increasing "specials" gives you -a high chance of resources/square, and huts determines how many -freebie huts there are. Increasing the amount of settlers or -explorers one starts with makes the game go faster, and allows people -to survive "those $#@! barbarians" which sometimes live in huts. - - The rail-related settings determine how much more a square -will produce in food/trade/production with a railroad on it, and the -foodbox setting determines how much food each person in a city has to -have before a new person can be added. - - As for the rest, higher "mountains" means a more mountainous -map, higher "deserts" means more deserts, etc. - - -Q. How do I get _____ tech? - -Look the tech up in the online help. It will show you the -technologies you need to get first. - -You could read the technology ruleset in -'data/classic/techs.ruleset'. It shows a list of all the techs, -and what techs are necessary to get them. - - -Q. What kinds of military units are the most useful? - - For Attack: - - Armor (tanks), Helicopters, Cruise Missiles, Battleships, - Transports, Nuclears, Howitzers, Bombers. - - For Defense: - - Armor (tanks), Mech Inf., Howitzers, Battleships, - Cruise Missiles, Nuclears. - -Remember, the best defense is a strong offense. - - -Additions to this document are welcome! diff --git a/doc/README.governor b/doc/README.governor deleted file mode 100644 index 661e605040..0000000000 --- a/doc/README.governor +++ /dev/null @@ -1,225 +0,0 @@ - - Citizen Governor (aka Citizen Management Agent, or CMA) -========================================================= - -The Citizen Governor is designed to help you manage your cities, i.e. -deploy the workers on the available tiles around (or make them -scientists, taxmen, or even entertainers), to get the most out of the -city. You can switch the Governor on or off at any time for any city, -but there are some handicaps (explained below), if you have governor -controlled and non-governor-controlled cities nearby. - -The heart of Governor system is an optimizing algorithm, that tries -to deploy the workers of a city in such a way, that a user-defined -goal is achieved as much as possible. You know probably, there is -already a kind of optimizing, when you open a city, and click on -the center tile (the city symbol) of the mini map. This optimization -tries to maximize mostly the science output; but it doesn't care about -disorder. - -The new City Management Agent goes far beyond this old form of -optimizing. First, it performs this task every time anything changes -with the city. If the city grows or shrinks, troops go in or out, -tiles get irrigation or mining, or are occupied by an enemy, the Governor -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. - - - Usage -========= - -You can set up the Governor for a city by opening the city window and -clicking on the Governor 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 a new 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 -gauges how 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 shields per round by setting the production -surplus to 5. The most powerful constraint, though, is the Celebrate -constraint, which makes the city celebrate at once (which usually takes -effect the round after you change it). - -It is obvious that the Governor can't fulfill all these constraints in -every case. Whenever the constraints can't be fulfilled, the Governor -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, see below), 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" to switch on the Governor. If this button's text is greyed, -either the Governor 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 Governor deliberately, click "Release -city". - - - Advanced Usage -================== - -Usually the goal(s) of your cities depend on the phase your game is in, -whether you want to spread widely, grow quickly, research advanced techs -or wage war. You may want to set up a high factor for science to research, -or a high shields factor to produce units. The highest factor available -is 25, that means: if the shields factor is set to 25, and other to 1, -the Governor prefers a single shield over 25 gold (or trade also). This is -pretty much because money can buy units too. That also means that -the Governor is indifferent about producing gold, science, luxury, and food; -but when you wage war, you usually prefer gold or luxury. So it's probably -a good idea to set a second (or even third) preference for the city's output, -e.g. gold factor 5. That still prefers 1 shield over 5 gold (and 1 gold over 5 -food or anything else). - -Constraints aren't useful in all cases. If you want a high income, -it's probably better to set the gold factor to 25, than to set a -minimal surplus of 5 or so. Because a big city can make more gold than -a small one, you'd end up setting a different surplus for each city. - -However, if the shields surplus of a city is below zero, it cannot -support all of its units any more. You will lose some of the units the -city supports. If the food surplus is negative, the city will starve -and eventually (when the granary is empty) shrink. This may be -intended, but if the city supports any settlers, you will lose them -before the city shrinks. Constraints can also have a warning function. - -Which constraints can be fulfilled depends widely on the global -science, tax, and luxury rates. E.g. a gold surplus >= 0 is easier to -fulfill with a higher tax rate than a lower one. You should always -consider to change these rates, when you going to change the Governor -settings for the most of your cities. - -Hint: To avoid accidentally releasing your cities, when you change the -rates, it is best to do so from within the tax dialog rather than from -the rates display in the main window. - - - Drawbacks -============= - -The Governor is a very powerful tool, which not only releases you from the -micromanagement of your cities, but gives you more performance than -you have ever seen (well, for most players). - -There are some drawbacks, though. Once you've switched on the Governor, it -grabs any good tile it can get. So you encounter very hard times -trying to manage a city nearby a Governor-controlled one. This is true for -the city window and the main map worker's interface as well. If you -want to have Governor-controlled and "handmade" cities, they probably -should be on different islands. - -There are several situations where the Governor can't fulfill the -requirements just temporarily, e.g. when you move a ship from one city -to another, or when an enemy walks through your country. The Governor -passes back control in these cases, and you have to reenable it -manually. A general approach to prevent this might be, to set the -minimal surpluses as low as possible (-20). Of course you must be -careful with the food and shield surpluses. - -While the Governor does a really good job for a single city, no tile will -ever be released for the good of another city. Also, the Governor controlled -cities are computed in a more random order; the results may depend on it and -change, when a recalculation is done (when tax changes e.g.). So, no -guarantee is given that the overall results are always optimal. - - - Settings file -================= - -The client allows the user to load and save preset parameters for the -agent. Choosing "Save Settings" from the "Game" menu will not only -save your general options and message options, but it will save any -changes you made to you Governor presets as well. - -The format for the options file (usually ~/.freeciv/.freeciv-client-rc-X.Y , where X.Y -is the version of freeciv in use) is as follows (in case you which to change -these presets manually, i.e. with a text editor). - -Under the heading [cma], is a "number_of_presets". This should be set -to the number of presets that are present in the options file. If you -manually add or remove a preset, you need to change this number as -appropriate. - -After this, is an array that houses the presets. Here is the header: - -preset={ "name","minsurp0","factor0","minsurp1","factor1","minsurp2", -"factor2","minsurp3","factor3","minsurp4","factor4","minsurp5", -"factor5","reqhappy","factortarget","happyfactor" - -so the order of the preset should be as follows: - -name of preset, minimal surplus 0, factor 0, ... , -require city to be happy, what the target should be [0,1], -the happiness factor - -Currently there are 6 surpluses and factors. They are: -0 = food, 1 = production, 2 = trade, 3 = gold, 4 = luxury, -5 = science - -Also currently, "factortarget" is not changeable within the client, -see "client/agents/cma_core.h" for more information. - -The array should be terminated with a '}'. - -Here are 21 presets you can use if you can't come up with some on -your own: - -"Max food",0,10,0,1,0,1,0,1,0,1,0,1,0,0,1 -"Max production",0,1,0,10,0,1,0,1,0,1,0,1,0,0,1 -"Max trade",0,1,0,1,0,10,0,1,0,1,0,1,0,0,1 -"Max tax",0,1,0,1,0,1,0,10,0,1,0,1,0,0,1 -"Max luxury",0,1,0,1,0,1,0,1,0,10,0,1,0,0,1 -"Max science",0,1,0,1,0,1,0,1,0,1,0,10,0,0,1 -"+2 food",2,1,0,1,0,1,0,1,0,1,0,1,0,0,1 -"+2 production",0,1,2,1,0,1,0,1,0,1,0,1,0,0,1 -"+2 trade",0,1,0,1,2,1,0,1,0,1,0,1,0,0,1 -"+2 gold",0,1,0,1,0,1,2,1,0,1,0,1,0,0,1 -"+2 luxury",0,1,0,1,0,1,0,1,2,1,0,1,0,0,1 -"+2 science",0,1,0,1,0,1,0,1,0,1,2,1,0,0,1 -"Max food no gold limit",0,10,0,1,0,1,-20,1,0,1,0,1,0,0,1 -"Max production no gold limit",0,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 -"Max trade no gold limit",0,1,0,1,0,10,-20,1,0,1,0,1,0,0,1 -"Max gold no gold limit",0,1,0,1,0,1,-20,10,0,1,0,1,0,0,1 -"Max luxury no gold limit",0,1,0,1,0,1,-20,1,0,10,0,1,0,0,1 -"Max science no gold limit",0,1,0,1,0,1,-20,1,0,1,0,10,0,0,1 -"Max food+prod. no gold limit",0,10,0,10,0,1,-20,1,0,1,0,1,0,0,1 -"Max food+prod.+trade",0,10,0,10,0,10,0,1,0,1,0,1,0,0,1 -"Max all",0,1,0,1,0,1,0,1,0,1,0,1,0,0,1 - -here are 6 more that have been added as an afterthought: - -"+1 food, max prod. no gold limit",1,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 -"+2 food, max prod. no gold limit",2,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 -"+3 food, max prod. no gold limit",3,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 -"+4 food, max prod. no gold limit",4,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 -"+5 food, max prod. no gold limit",5,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 -"+6 food, max prod. no gold limit",6,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 - -and even more, some with multiple goals: - -"research at any cost",0,1,0,5,-20,1,-20,1,-20,1,-20,25,0,0,1 -"celebration and growing",1,1,0,25,-20,1,-20,12,-20,1,-20,1,1,0,1 -"grow at any cost",1,25,0,5,-20,1,-20,1,-20,1,-20,5,0,0,1 -"research and some shields",0,1,0,8,0,1,-3,1,0,1,0,25,0,0,1 -"shields and a bit money",0,1,0,25,0,1,-3,3,0,1,0,1,0,0,1 -"many shields and some money",0,1,0,25,0,1,0,9,0,1,0,1,0,0,1 -"shields and some research",0,1,0,25,0,1,-2,1,0,1,0,8,0,0,1 -"celebrate and grow at once",1,1,0,25,-20,1,-20,1,-20,1,-20,8,1,0,1 - -Last updated: 10 Apr 2015 diff --git a/doc/README.modpack_installer b/doc/README.modpack_installer deleted file mode 100644 index 0aa335606e..0000000000 --- a/doc/README.modpack_installer +++ /dev/null @@ -1,363 +0,0 @@ -=========================================================================== - Modpack installer tool -=========================================================================== - -Installing modpacks -------------------- - -The modpack installer is a simple tool to download custom Freeciv -content called "modpacks" from the Internet, and automatically install -them into the correct location to be used by the Freeciv client and -server. - -A "modpack" can consist of one or more of: - - 'rulesets' for game rules - - 'scenarios' for game maps (with or without players/cities/etc) - - 'tilesets' for game graphics - - 'soundsets' or 'musicsets' for sound effects and in-game music - -They can be installed using the modpack installer tool -'freeciv-modpack-qt' that comes with the standard installation. -There is also a command-line-only tool called 'freeciv-modpack', -which is mainly useful for headless game servers. - -In standard Freeciv21 builds, when you start the graphical modpack -installer, it will show a list of modpacks curated by the Freeciv21 -developers. You can select one and press "Install modpack"; the tool -will download the files for the selected modpack, and any other -modpacks it depends on, and install them ready for the main Freeciv21 -programs to use. - -You can also point the installer at modpacks or lists on other servers: - - * If someone has given you an individual modpack URL (ending in - '.json'), you can paste it into the "Modpack URL" box, and when - you press "Install modpack", the modpack will immediately be - downloaded and installed. - (If you have been given a URL ending up '.modpack' or '.mpdl', that - is probably for Freeciv and not Freeciv21.) - - * If someone has given you a URL for a list of modpacks (also - ending in '.json') and you want to browse them with the standard - Freeciv modpack installer build, you need to start the tool with - that URL on its command line, for instance: - - freeciv-modpack --List https://example.com/3.1/my-modpacks.list - - (note the capital letter in '--List') - -(The tool has some other command-line options, but most users will not -need to use them. Use --help for a list of them.) - -Once you have installed a modpack, how you use it depends on the modpack -type: - - - Scenarios (maps) should be listed under 'Start scenario game' from - the client start page, or from the game server prompt via - '/list scenarios'. - (For network play, scenarios need only be installed on the game - server.) - - - Rulesets should appear on the 'Ruleset' drop-down from the client's - 'Start new game' page. On the game server, you can load a ruleset - with '/read ' or failing that perhaps '/set rulesetdir '. - (For network play, rulesets need only be installed on the game - server.) - - - Tilesets should appear for selection in the local client options, in - the appropriate topology-specific 'Tileset' drop-down under 'Graphics'. - (Tilesets should be installed on the game client machine.) - - - Soundsets and musicsets should appear in the dropdowns on the 'Sound' - page of the local client options. - (These should be installed on the game client machine.) - -With standard Freeciv21 builds, modpacks get installed into a per-user -area, not into the main Freeciv21 installation. So you shouldn't need any -special permissions to download them, and if you uninstall the Freeciv21 -game, any modpacks you downloaded are likely to remain on your system. -Conversely, if you delete downloaded modpacks by hand, the standard -rulesets, tilesets etc supplied with Freeciv21 won't be touched. - -The precise location where files are downloaded to depends on your build -and platform. For Unix systems is is likely to be under the hidden -'.local/share/freeciv21' directory in your home directory. It is likely -to be near where the Freeciv21 client stores its saved games. - -Most modpacks are specific to a particular major version of Freeciv21; for -instance, while a 3.0 ruleset or tileset can be used with all Freeciv21 -3.0.x releases, it cannot be used as-is with any 3.1.x release. So, most -modpacks are installed in a specific directory for the major version, -such as ~/.local/share/freeciv21/3.1/ on Unix. (The modpack installer -displays which version it will install for at the top of its window.) - -An exception to this is scenario maps; scenarios created for one version -of Freeciv21 can usually be loaded in later versions, so they are -installed in a version-independent location (typically -~/.local/share/freeciv21/scenarios/ on Unix). - -Once a modpack is installed, there is no uninstall action, and if you -remove the files by hand, the installer will still consider the modpack -to be installed; the installer maintains its own database -(.control/modpacks.db) listing which modpack versions are installed, but -does not keep track of which files were installed by which modpack. If -the database gets of of sync with reality (or is deleted), it's -harmless for already installed modpacks and the main Freeciv21 programs -(which do not consult the database), but can confuse the modpack -installer's dependency tracking later. - -Modpacks consist mostly of data files read by the Freeciv21 engine; they -do not contain compiled binary code (and are thus platform-independent). -Rulesets can contain code in the form of Lua scripts, but this is -executed in a sandbox to prevent obvious security exploits. Modpacks are -installed to a specific area and cannot overwrite arbitrary files on -your system. Nevertheless, you should only install modpacks from sources -you trust. - - -Serving modpacks for the installer ----------------------------------- - -The rest of this document discusses how to set up a web server so that -users can download modpacks you publish. (If you just want to install -modpacks, you need not read on.) - -To host modpacks, you just need a web server that can host plain static -files; you do not need to run any custom code or frameworks on that web -server, just to publish files with a specific layout, detailed below. - -On the modpack server, there are up to three layers of files required: - 1. A list of available modpacks (optional, advanced). - 2. One control file per modpack. - 3. The individual files comprising the modpacks. - -Each of these layers is described in detail below. - -Each layer refers to files in the next layer down. References can be -with relative URLs (so that a modpack or set of modpacks can be moved -without changing any file contents), or with absolute URLs (so that the -different layers can be hosted on different web servers). - -Almost all of these file formats are specific to one major version of -Freeciv21; this document only describes the formats for the major -version of Freeciv21 it is shipped with. - - -1. List of modpacks - -This is only needed if you want to let users browse a list of available -modpacks before choosing one to install. To look at your modpack list -instead of the standard one, users will usually have to start the -modpack installer with non-standard arguments (see above). - -The modpack list is a standard JSON file with a specific structure. - -Here's an example: - -{ - "info": { - "options": "+modpack-index-1.0", - "message": "Example modpack list loaded successfully" - }, - "modpacks": [ - { - "name": "Example", - "version": "0.0", - "license": "WTFPL", - "type": "Modpack", - "url": "https://example.com/example.json", - "notes": "This is an example" - } - ] -} - -This file uses the modpack index format version 1.0, as is indicated in -the info.options field. The optional info.message is displayed on the -status line when the modpack installer starts up. It should be kept to -one line. - -The modpacks list contains a list of modpacks. This example contains just -one modpack. Each modpack may contain the following fields: - - "name", "version", "type": - These three fields should match those in the .json file which - "URL" links to. - - "subtype": - Optional free text. For tilesets or scenarios, conventionally - indicates the map topology with one of "overhead", "iso", "hex", - or "hex & iso" (and these will be localised). Otherwise "-". - - "license": - Free text summarising the distribution terms for the modpack - content (by naming a well-known license, not quoting the full - license text!). Consider using SPDX identifiers - (https://spdx.org/licenses/). - - "URL": - The URL to a .json file for the individual modpack. - The URL can be either relative (in which case it's relative to - the URL of modpack.list) or absolute (which can be on some other - web server). - - "notes": - Optional free text; usually shown as a tooltip. - - -2. *.json control file, defining an individual modpack - -This is the core control file for a modpack, specifying what files it -contains, where to download them from, and where they are installed. - -Some modpack authors will just publish the URL of an .json file -directly, for users to give to the modpack installer tool. (There -doesn't have to be a modpack.list file anywhere that refers to the -.json file.) - -Again, this is a file in standard JSON format. Its filename must end -in ".json". - -Here is an example of a modpack control file: -{ - "info": { - "options": "+modpack-1.0", - "base_url": ".", - "name": "Some ruleset", - "type": "Modpack", - "version": "0.0" - }, - "files": [ - "some_ruleset.serv", - "some_ruleset.tilespec", - "some_ruleset/nation/german.ruleset", - "some_ruleset/nation/indian.ruleset", - ... - ] -} - -The "info" section has overall control information: - - "options": Defines the version of the file format. Should be exactly - as shown in the example. - - "name": - A short name for the modpack. This is used for version and - dependency tracking, so should not contain minor version - information, and should not change once a modpack has been - released for a given major version of Freeciv21. Case-insensitive. - - "version": - Textual version information. If another modpack uses this one as a - dependency, this string is subject to version number comparison - (using the rules of Freeciv21's 'cvercmp' library, which should give - sensible results for most version numbering schemes). - - "type": - This must be one of the following: - - "Ruleset" (foo.serv, foo/*.ruleset, foo/*.lua, etc) - - "Tileset" (foo.tilespec, foo/*.png, etc) - - "Soundset" (foo.soundspec, foo/*.ogg, etc) - - "Musicset" (foo.musicspec, foo/*.ogg, etc) - - "Scenario" (foo.sav; installed to a version-independent location) - - "Modpack": conventionally used for modpacks that contain more - than one of the above kinds of material - - "Group": contains no files but only depends on other modpacks - At the moment, only "Scenario" causes special behavior. - - "base_url": - URL to prepend to the "src" filenames in the "files" list. - May be relative to the .json file (starting with "./"), or - absolute (in which case the files can be on some web server - different to where the .json file lives). - -The "files" list defines the individual files comprising your modpack. -(It must list every file individually; any files in the same directory -on the webserver that are not listed will not be downloaded.) -Entries can be strings as shown above, in which case the same file name -is used for downloading (relative to info.base_url) and installing -(relative to the data directory). If the installed name is different -from the name on the server, the following syntax can be used instead: - -{ - "url": "some-remote-file", - "dest": "where-to-install-it" -} - -The URL can be either relative (to info.base_url) or absolute. The two -syntaxes can be mixed in the same modpack. - -Note that "/" (and not "\") should be used to separate directories. - -Some advice on the structure of files in modpacks: - - * You should generally install files in a directory named after the - modpack, with a few exceptions (.serv, .tilespec, .soundspec, and - .musicspec files must be installed to the top level, and should - reference files in your subdirectory). - - Individual files' and directories' install names should usually not - embed version numbers, dates, etc, so that when a new version of - modpack X is installed, it cleanly overwrites the old version, rather - than leaving both cluttering up the user's installation. - - * The modpack installer does not stop different modpacks overwriting - each other's files, so published modpacks should be disciplined about - namespace usage. If you've derived from someone else's modpack, you - should probably give your derivative new filenames, so that both can - be installed simultaneously. - - * There is no 'white-out' facility to delete files from a user's - installation -- if a newer version of a modpack has fewer files than - an old one, the old file will persist in some users' installations, - so your modpacks should be designed to be tolerant of that. - - * At the moment, there is no restriction on what kind of files a given - "type" can install, but modpacks should stick to installing the - advertised kinds of content. It's OK to install extra files such as - documentation in any case (LICENSE/COPYING, README.txt, etc). - - * If your modpack contains a ruleset, you should usually install a - .serv file at the top level (which can be a one-line file consisting - of "rulesetdir ", as this is needed for the server to enumerate - the available rulesets. - -In some cases, a modpack may depend on other modpacks, for instance if -it reuses some of their files. This can be handled by declaring a -dependency with respect to the other modpack. Dependencies are listed in -the optional "dependencies" list of the JSON file. Each entry in that list -must contain the following object: - -{ - "modpack": "...", - "url": "...", - "type": "...", - "version": "..." -} - -The keys are explained below: - - "modpack": - What the dependency modpack calls itself when installed (that is, - "name" from its .json file). - - "url": - URL to download modpack if needed. Can be relative or absolute. - - "type": - Must match "type" from dependency's .json file. - - "version": - Minimum version of dependency (as declared in its .json file). - Subject to version number comparison algorithm. - -If the modpack installer thinks the required version, or a newer -version, of the dependency is already installed, it will do nothing, -otherwise it will download the dependency modpack (and any of its own -dependencies, recursively). - - -3. Individual modpack files - -These are the files comprising the modpack (*.ruleset, *.png, etc), that -will be copied verbatim to the user's Freeciv21 data directory and read by -the Freeciv21 client and server. The modpack installer does not modify the -files in any way. - -The files must be hosted individually on the web server; the modpack -installer tool cannot unpack any archives such as .zip files. -(Individual scenarios can be compressed, e.g. .sav.gz, as the Freeciv21 -engine can uncompress these files.) - -Because the *.json file can change the file paths / names on download, -the layout on the modpack server doesn't have to correspond with the -installed layout. An individual file can be shared between multiple -modpacks, if you want. - -How to write modpacks is beyond the scope of this document -- see -README.rulesets, README.graphics, etc for some clues. diff --git a/docs/Developing/index.rst b/docs/Developing/index.rst new file mode 100644 index 0000000000..2ec5030310 --- /dev/null +++ b/docs/Developing/index.rst @@ -0,0 +1,11 @@ +Developing +********** + +Developing + The Developing category is an area for documentation editors to provide information on how to alter the + source code of Freeciv21 and contribute to the project in general. + + +.. toctree:: + style-guide.rst + :maxdepth: 1 diff --git a/docs/Developing/style-guide.rst b/docs/Developing/style-guide.rst new file mode 100644 index 0000000000..bd1da2e6da --- /dev/null +++ b/docs/Developing/style-guide.rst @@ -0,0 +1,117 @@ +Documentation Style Guide +************************* + +.. Custom Interpretive Text Roles for longturn.net/Freeciv21 +.. role:: unit +.. role:: improvement +.. role:: wonder + +The Longturn community uses the Python based Sphinx system to generate the documentation available on this +website and in the :file:`doc` directory in the released tarball. Sphinx takes plain text files formatted +with a superset of markdown called reStructuredText (ReST). Sphinx reStructuredText is documented here: +https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html + +This style guide is mostly meant for documentation authors to ensure that we keep a consistent look and feel +between authors. + +Headings +======== + +Headings create chapter breaks between sections of a document as well as provide the title. + +Heading 1 + Heading 1 is used to for the title of the page/document. The asterisk is used to denote Heading 1 like + this: + +.. code-block:: rst + + This is an awesome page title + ***************************** + + +Heading 2 + Heading 2 is used to create chapter markers or other major breaks in a document. The equal sign is used + to denote Heading 2 like this: + +.. code-block:: rst + + This is a chapter marker + ======================== + + +Heading 3 + Heading 3 is used to break a chapter into sub-chapters in a document. Heading 3 is not shown on the left + side table of contents since we specifcally only show 2 levels in the :file:`conf.py` configuration file. + The dash is used to denote Heading 3 like this: + +.. code-block:: rst + + This is heading 3 + ----------------- + + +Interpreted Text Roles +====================== + +Interpreted text roles are special code blocks that are inserted in line with regular text to create user +interface markup elements to bring attention to something or make it more obvious to the reader what you +want to do. Interpreted text roles are simply a code word surrounded by a colon on both sides and the text +you want to alter is placed inside back-ticks. + +* :literal:`:doc:` -- Doc is used to create a hyperlink reference between documents in the documentation + system. +* :literal:`:emphasis:` -- Emphasis is used to :emphasis:`bring attention to something`. +* :literal:`:file:` -- File is used for file names and paths such as :file:`~/.local/share/freeciv21/saves` +* :literal:`:guilabel:` -- GUI Label is used to bring attention to someting on the screen like the + :guilabel:`Next` button on the installer wizard +* :literal:`:literal:` -- Literal is used when you want to note a text element in its raw form. +* :literal:`:menuselection:` -- Menu Selection is used to give the path of menu clicks such as + :menuselection:`Game --> Options --> Local Options`. To create the arrow character in between the options + you will place a text arrow like this: :literal:`-->` in between the selection items. +* :literal:`:strong:` -- Strong is used to :strong:`bold some text`. +* :literal:`:title-reference:` -- Title Reference is used notate a :title-reference:`title entry` in the + in-game help or to refer to a page in the documentation without giving an actual hyperlink reference + (see :literal:`:doc:` above). + +The docutils specification allows for custom Interpreted Text Roles and we use this feature. The docutils +documentation on this feature is available here: +https://docutils.sourceforge.io/docs/ref/rst/directives.html#custom-interpreted-text-roles + +* :literal:`:unit:` -- This provides an opportunity to highlight a Freeciv21 unit, such as the + :unit:`Musketeer` +* :literal:`:improvement:` -- This provides an opportunity to highlight a Freeciv21 building or city + improvement, such as the :improvement:`Granary`. +* :literal:`:wonder:` -- This provides an opportunity to highlight a Freeciv21 small or great wonder, such as + the :wonder:`Pyramids`. + +Admonition Directives +===================== + +Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. Typically, +an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title +matching the admonition type. We use some of the standard admonitions in our documentation as well. + +* :literal:`.. attention::` -- Use attention to bring a very important high profile item to the reader's + attention. + +.. attention:: + This is a really important message! Don't forget to eat breakfast every day. + +* :literal:`.. todo::` -- Use To Do as a reminder for documentation editors to come back and fix things at + a later date. + +.. todo:: + Come back and fix something later. + +* :literal:`.. note::` -- Use the "note" as we way to give more information to the reader on a topic. + +.. note:: + It's important to note that Freeciv21 is really fun to play with group's of people online. + +* :literal:`.. code-block:: rst` -- The code block is an excellent way to display actual code or any + pre-formatted plain text. + +.. code-block:: rst + + This is a code block showing some pre-formatted text. + diff --git a/docs/General/faq.rst b/docs/General/faq.rst new file mode 100644 index 0000000000..77480b95fd --- /dev/null +++ b/docs/General/faq.rst @@ -0,0 +1,635 @@ +Frequently Asked Questions (FAQ) +******************************** + +.. Custom Interpretive Text Roles for longturn.net/Freeciv21 +.. role:: unit +.. role:: improvement +.. role:: wonder + +The following page has a listing of frequenty asked questions with answers about Freeciv21. + +Gameplay +======== + +OK, so I installed Freeciv21. How do I play? +-------------------------------------------- + +Start the client. Depending on your system, you might choose it from a menu, double-click on the +:file:`freeciv21-client` executable program, or type :file:`freeciv21-client` in a terminal. + +Once the client starts, to begin a single-player game, select :guilabel:`Start new game`. Now edit your +game settings (the defaults should be fine for a beginner-level single-player game) and press the +:guilabel:`Start` button. + +Freeciv21 is a client/server system. But in most cases you don't have to worry about this; the client +starts a server automatically for you when you start a new game. + +.. attention:: The Windows Server currently has a defect that does not allow it to run automatically from + the client. See Issue `#341 `_ as well as work in + progress pull request `#462 `_. The current work around is + to manually start the server and a game and then connect to it via the client. + + This defect is not present in the Linux builds. + +Once the game is started you can find information in the :guilabel:`Help` menu. If you've never played a +Civilization-style game before you may want to look at help on :title-reference:`Strategy and Tactics`. + +You can continue to change the game settings through the :menuselection:`Game --> Options --> Server +Options` menu. Type :literal:`/help` in the chatline (or server command line) to get more information about +server commands. + +Detailed explanations of how to play Freeciv21 are also in the :file:`./doc/README` file distributed with +the source code, and in the in-game help. + +.. todo:: Update reference to README when it is converted to documentation project. + +How do I play multiplayer? +-------------------------- + +You can either join a network game run by someone else, or host your own. You can also join one of the many +games offered by the longturn.net community. + +To join an open network game, choose :guilabel:`Connect to network game` and then :guilabel:`Internet +servers`. A list of active servers should come up; double-click one to join it. + +To host your own game, we recommend starting a separate server by hand. + +To start the server, enter :file:`freeciv21-server` in a terminal or by double-clicking on the executable. +This will start up a text-based interface. + +If all players are on the same local area network (LAN), they should launch their clients, choose +:guilabel:`Connect to Network game` and then look in the :guilabel:`Local servers` section. You should see +the existing server listed; double-click on it to join. + +To play over the Internet, players will need to enter the hostname and port into their clients, so the game +admin will need to tell the other players those details. To join a longturn.net server you start by clicking +:guilabel:`Connect to Network Game` and then in the bottom-left of the dialog fill in the +:guilabel:`Connect`, :guilabel:`Port`, and :guilabel:`Username` fields provided by the game admin. Once +ready, click the :guilabel:`Connect` button at the botton-right, fill in your longturn.net password in the +:guilabel:`Password` box and you will be added to the game. + +.. note:: Hosting an Internet server from a home Internet connection is often problematic, due to + firewalling and network address translation (NAT) that can make the server unreachable from the wider + Internet. Safely and securely bypassing NAT and firewalls is beyond the scope of this FAQ. + +Where is the chatline you are talking about, how do I chat? +----------------------------------------------------------- + +The chatline is located at the bottom of the messages window. You can activate and enlarge the chat panel by +double-clicking on the bottom row of text. + +The chatline can be used for normal chatting between players, or for issuing server commands by typing a +forward-slash :literal:`/` followed by the server command. + +See the in-game help on :title-reference:`Chatline` for more detail. + +Why can't I attack another player's units? +------------------------------------------ + +You have to declare war first. See the section for `How do I declare war on another player?`_ below. + +.. note:: In some rulesets, you start out at war with all players. In other rulesets, as soon as you + make contact with a player, you enter armistise towards peace. At lower skill levels, AI players offer + you a cease-fire treaty upon first contact, which if accepted has to be broken before you can attack + the player's units or cities. The main thing to remember is you have to be in the war diplomatic state + in order to attack an enemy. + +How do I declare war on another player? +--------------------------------------- + +Go to the :guilabel:`Nations` page, select the player row, then click :guilabel:`Cancel Treaty` at the top. +This drops you from emphasis:`cease fire`, emphasis:`armistice`, or emphasis:`peace` into emphasis:`war`. If +you've already signed a permanent emphasis:`alliance` treaty with the player, you will have to cancel +treaties several times to get to emphasis:`war`. + +See the in-game help on :title-reference:`Diplomacy` for more detail. + +.. note:: The ability to arbitrarily leave emphasis:`peace` and go to emphasis:`war` is also heavily + dependent on the form of governement your nation is currently ruled by. See the in-game help on + :title-reference:`Government` for more details. + +How do I do diplomatic meetings? +-------------------------------- + +Go to the :guilabel:`Nations` page, select the player row, then choose :guilabel:`Meet` at the top. Remember +that you have to either have contact with the player or an embassy established in one of their cities. + +How do I trade money with other players? +---------------------------------------- + +If you want to make a monetary exchange, first initiate a diplomatic meeting as described in the section +about `How do I do diplomatic meetings?`_ above. In the diplomacy dialog, enter the amount you wish to give in +the gold input field on your side or the amount you wish to receive in the gold input field on their side. +With the focus in either input field, press :guilabel:`Enter` to insert the clause into the treaty. + +How can I change the way a Freeciv21 game is ended? +--------------------------------------------------- + +A standard Freeciv21 game ends when only allied players/teams are left alive; when a player's spaceship +arrives at Alpha Centauri; or when you reach the ending turn - whichever comes first. + +For longturn.net multi-player games, the winning conditions are announced before the game begins. + +For local games, you can change the default ending turn by changing the endturn setting. You can do this +through the :menuselection:`Game --> Options --> Remote Server` menu or by typing into the chatline something +like: + +.. code-block:: rst + + /set endturn 300 + + +You can end a running game immediately with: + +.. code-block:: rst + + /endgame + + +For more information, try: + +.. code-block:: rst + + /help endgame + + +If you want to avoid the game ending by space race, or require a single player/team to win, you can change +the victories setting - again either through the Server Options dialog or through the chatline. For instance +this changes from the default setting spacerace|allied to disallow allied victory and space race: + +.. code-block:: rst + + /set victories "" + + +You can instead allow space races without them ending the game by instead changing the endspaceship setting. + +A single player who defeats all enemies will always win the game -- this conquest victory condition cannot +be changed. + +In rulesets which support it, a cultural domination victory can be enabled, again with the victories setting. + +My irrigated grassland produces only 2 food. Is this a bug? +----------------------------------------------------------- + +No, it isn't. It's a feature. Your government is probably despotism, which has a -1 output whenever a tile +produces more than 2 units of food/production/trade. You should change your government (See the in-game help +on :title-reference:`Government` for more detail) to get rid of this penalty. + +This feature is also not 100% affected by the form of government. There are some Small and Great Wonders +in certain rulesets that get rid of the output penalty. + +How do I play against computer players? +--------------------------------------- + +See also the `How do I create teams of AI or human players?`_ section below. + +In most cases when you start a single-player game you can change the number of players, and their +difficulty, directly through the spinbutton. + +.. note:: The number of players here includes human players (an :literal:`aifill` of :literal:`5` adds AI + players until the total number of players becomes 5). + +If you are playing on a remote server, you'll have to do this manually. Change the :literal:`aifill` server option +through the :guilabel:`Remote Server` options dialog, or do it on the chatline with something like: + +.. code-block:: rst + + /set aifill 30 + + +Difficulty levels are set with the :literal:`/cheating`, :literal:`/hard`, :literal:`/normal`, +:literal:`/easy`, :literal:`/novice`, and :literal:`/handicapped` commands. + +You may also create AI players individually. For instance, to create one hard and one easy AI player, enter: + +.. code-block:: rst + + /create ai1 + /hard ai1 + /create ai2 + /easy ai2 + /list + + +More details are in the :file:`./doc/README` file supplied with Freeciv and the online manual on this site. + +.. todo:: Update reference to README when it is converted to documentation project. + +Can I build up the palace or throne room as in the commercial Civilization games? +--------------------------------------------------------------------------------- + +No. This feature is not present in Freeciv21, and will not be until someone draws the graphics for it. + +Can I build land over sea/transform ocean to land? +-------------------------------------------------- + +Yes. You can do that by placing :unit:`engineer` on a :unit:`transport` and going to the ocean tile you want +to build land on (this must be in a land corner). Click the :unit:`transport` to display a list of the +transported :unit:`engineers` and activate them. Then give them the order of transforming this tile to +swamp. This will take a very long time though, so you'd better try with 6 or 8 :unit:`engineers` at a time. +There must be 3 adjacent land tiles to the ocean tile you are transforming. + +Can I change settings or rules to get different types of games? +--------------------------------------------------------------- + +Of course. Before the game is started, you may change settings through the :guilabel:`Server Options` +dialog. You may also change these settings or use server commands through the chatline. If you use the +chatline, use the: + +.. code-block:: rst + + /show + +command to display the most commonly-changed settings, or + +.. code-block:: rst + + /help + + +to get help on a particular setting, or + +.. code-block:: rst + + /set + + +to change a setting to a particular value. After the game begins you may still change some settings, but not +others. + +You can create rulesets or strong:`modpacks` - alternative sets of units, buildings, and technologies. Several +different rulesets come with the Freeciv21 distribution, including a civ1 (Civilization 1 compatibility mode), +and civ2 (Civilization 2 compatibility mode). Use the :literal:`rulesetdir` command to change the +ruleset (as in :literal:`/rulesetdir civ2`). + +How compatible is Freeciv21 with the commercial Civilization games? +------------------------------------------------------------------- + +Freeciv21 was created as a multiplayer version of Civilization |reg| with players moving simultaneously. +Rules and elements of Civilization II |reg|, and features required for single-player use, such as AI +players, were added later. + +This is why Freeciv21 comes with several game configurations (rulesets): the civ1 and civ2 rulesets implement +game rules, elements and features that bring it as close as possible to Civilization I and Civilization II +respectively, while other rulesets such as the default classic ruleset tries to reflect the most popular +settings among Freeciv21 players. Unimplemented Civilization I and II features are mainly those that would +have little or no benefit in multiplayer mode, and nobody is working on closing this gap. + +Little or no work is being done on implementing features from other similar games, such as SMAC, CTP or +Civilization III. + +So the goal of compatibility is mainly used as a limiting factor in development: when a new feature is added +to Freeciv21 that makes gameplay different, it is generally implemented in such a way that the +:emphasis:`traditional` behaviour remains available as an option. However, we're not aiming for absolute +100% compatibility; in particular, we're not aiming for bug-compatibility. + +My opponents seem to be able to play two moves at once! +------------------------------------------------------- + +He isn't, it only seems that way. Freeciv21's multiplayer facilities are asynchronous: during a turn, moves +from connected clients are processed in the order they are received. Server managed movement is executed in +between turns. This allows human players to surprise their opponents by clever use of goto or quick fingers. + +A turn in Longturn lasts 23 hours and it's always possible that he managed to log in twice between your two +consecutive logins. However, firstly, there is a mechanic that slightly limits this (known as unit wait time), +and secondly, this can't happen every time because now he has already played his move this turn and now +needs to wait for the Turn Change to make his next move. So, in the next turn, if you log in before him, now +it was you who made your move twice. If not, he can't :emphasis:`move twice` until you do. + +The primary server setting to mitigate this problem is :literal:`unitwaittime`, which imposes a minimum +time between moves of a single unit on successive turns. + +My opponent's last city is on a 1x1 island so I cannot conquer it, and they won't give up. What can I do? +--------------------------------------------------------------------------------------------------------- + +It depends on the ruleset, but often researching 'amphibious warfare' will allow you to build a +:unit:`marine`. Alternatively research 'combined arms' and either move a :unit:`helicopter` or airdrop a +:unit:`paratrooper` there. + +If you can't build :unit:`marines` yet, but you do have :unit:`engineers`, and other land is close-by, you +can also build a land-bridge to the island (i.e. transform the ocean). If you choose this route, make sure +that your :unit:`transport` is well defended! + +Why are the AI players so hard on 'novice' or 'easy'? +----------------------------------------------------- + +Short answer is... You are not expanding fast enough. + +You can also turn off Fog of War. That way, you will see the attacks of the AI. Just type :literal:`/set +fogofwar disabled` on the chat line before the game starts. + +Why are the AI players so easy on 'hard'? +----------------------------------------- + +Several reasons. For example, the AI is heavily playtested under and customized to the default ruleset and +server settings. Although there are several provisions in the code to adapt to changing rules, playing under +different conditions is quite a handicap for it. Though mostly the AI simply doesn't have a good, all +encompassing strategy besides :strong:`"eliminate nation x"`. + +To make the game harder, you could try putting some or all of the AI into a team. This will ensure that they +will waste no time and resources negotiating with each other and spend them trying to eliminate you. They +will also help each other by trading techs. See the question `How do I create teams of AI or human players?`_. + +You can also form more than one AI team by using any of the different predefined teams, or put some AI +players teamed with you. + +What distinguishes AI players from humans? What do the skill levels mean? +------------------------------------------------------------------------- + +AI players in Freeciv21 operate in the server, partly before all clients move, partly afterwards. Unlike the +client, they can in principle observe the full state of the game, including everything about other players, +although most levels deliberately restrict what they look at to some extent. + +All AI players can change production without penalty. Some levels (generally the harder ones) get other +exceptions from game rules; conversely, easier levels get some penalties, and deliberately play less well in +some regards. + +For more details about how the skill levels differ from each other, see the help for the relevant server +command (for instance :literal:`/help hard`). + +Other than as noted here, the AI players are not known to cheat. + +How do I play on a hexagonal grid? +---------------------------------- + +It is possible to play with hexagonal instead of rectangular tiles. To do this you need to set your topology +before the game starts; set this with Map topology index from the game settings, or in the chatline: + +.. code-block:: rst + + /set topology hex|iso|wrapx + + +This will cause the client to use an isometric hexagonal tileset when the game starts (go to +:menuselection:`Game --> Options --> Set local options` to choose a different one from the drop-down; +hexemplio and isophex are included with the game). + +You may also play with overhead hexagonal, in which case you want to set the topology setting to +:literal:`hex|wrapx`; the hex2t tileset is supplied for this mode. + +How do I create teams of AI or human players? +--------------------------------------------- + +The client has a GUI for setting up teams - just right click on any player and assign them to any team. + +You may also use the command-line interface (through the chatline.) + +First of all try the :literal:`/list` command. This will show you all players created, including human +players and AI players (both created automatically by aifill or manually with :literal:`/create`). + +Now, you're ready to assign players to teams. To do this you use the team command. For example, if there's +one human player and you want two more AI players on the same team, you can do to create two AI players and +put them on the same team you can do: + +.. code-block:: rst + + /set aifill 2 + /team AI*2 1 + /team AI*3 1 + + +You may also assign teams for human players, of course. If in doubt use the :literal:`/list` command again; +it will show you the name of the team each player is on. Make sure you double-check the teams before +starting the game; you can't change teams after the game has started. + +I want more action. +------------------- + +In Freeciv21, expansion is everything, even more so than in the single-player commercial Civilization games. +Some players find it very tedious to build on an empire for hours and hours without even meeting an enemy. + +There are various techniques to speed up the game. The best idea is to reduce the time and space allowed for +expansion as much as possible. One idea for multiplayer mode is to add AI players: they reduce the space per +player further, and you can toy around with them early on without other humans being aware of it. This only +works after you can beat the AI, of course. + +Another idea is to create starting situations in which the players are already fully developed. There is no +automated support for this yet, but you can create populated maps with the built-in editor. + +Community +========= + +Does Freeciv21 violate any rights of the makers of Civilization I or II? +------------------------------------------------------------------------ + +There have been debates on this in the past and the honest answer seems to be: We don't know. + +Freeciv21 doesn't contain any actual material from the commercial Civilization games. (The Freeciv21 +maintainers have always been very strict in ensuring that materials contributed to the Freeciv21 +distribution or Longturn website do not violate anyone's copyright.) The name of Freeciv21 is probably not a +trademark infringement. The user interface is similar, but with many (deliberate) differences. The game +itself can be configured to be practically identical to Civilization I or II, so if the rules of a game are +patentable, and those of the said games are patented, then Freeciv21 may infringe on that patent, but we +don't believe this to be the case. + +Incidentally, there are good reasons to assume that Freeciv21 doesn't harm the sales of any of the +commercial Civilization games in any way. + +Where can I ask questions or send improvements? +----------------------------------------------- + +Please ask questions about the game, its installation, or the rest of this site at the Longturn Discord +Channels at https://discord.gg/98krqGm. The :literal:`#questions-and-answers` channel is a good start. + +Patches and bug reports are best reported to the Freeciv21 bug tracking system at +https://github.com/longturn/freeciv21/issues/new/choose. + +Technical Stuff +=============== + +I've found a bug, what should I do? +----------------------------------- + +See the article on `Where can I ask questions or send improvements?`_. + +I've started a server but the client cannot find it! +---------------------------------------------------- + +By default, your server will be available on host :literal:`localhost` (your own machine), port +:literal:`5556`; these are the default values your client uses when asking which game you want to connect to. + +So if you don't get a connection with these values, your server isn't running, or you used :literal:`-p` to +start it on a different port, or your system's network configuration is broken. + +To start your local server, run :file:`freeciv21-server`. Then type :literal:`start` at the +server prompt to begin! + +.. code-block:: rst + + username@computername:~/games/freeciv21/bin$ ./freeciv21-server + This is the server for Freeciv21 version 3.0.20210721.3-alpha + You can learn a lot about Freeciv21 at https://longturn.readthedocs.io/en/latest/index.html + [info] freeciv21-server - Loading rulesets. + [info] freeciv21-server - AI*1 has been added as Easy level AI-controlled player (classic). + [info] freeciv21-server - AI*2 has been added as Easy level AI-controlled player (classic). + [info] freeciv21-server - AI*3 has been added as Easy level AI-controlled player (classic). + [info] freeciv21-server - AI*4 has been added as Easy level AI-controlled player (classic). + [info] freeciv21-server - AI*5 has been added as Easy level AI-controlled player (classic). + [info] freeciv21-server - Now accepting new client connections on port 5556. + + For introductory help, type 'help'. + > start + Starting game. + + +If the server is not running, you will :emphasis:`not` be able to connect to your local server. + +If you can't connect to any of the other games listed, a firewall in your organization/ISP is probably +blocking the connection. You might also need to enable port forwarding on your router. + +If you are running a personal firewall, make sure that you allow communication for :file:`freeciv21-server` +and the :file:`freeciv21-client` to the trusted zone. If you want to allow others to play on your server, +allow :file:`freeciv21-server` to act as a server on the Internet zone. + +How do I restart a saved game? +------------------------------ + +If for some reason you can't use the start-screen interface for loading a game, you can load one directly +through the client or server command line. You can start the client, or server, with the :literal:`-f` +option, for example: + +.. code-block:: rst + + freeciv21-server -f freeciv-T0175-Y01250-auto.sav.bz2 + + +Or you can use the :literal:`/load` command inside the server before starting the game. + +The server cannot save games! +----------------------------- + +In a local game started from the client, the games will be saved into the default Freeciv21 save directory +(typically :file:`~/.local/share/freeciv21/saves`). If you are running the server from the command line, +however, any savegames will be stored in the current directory. If the autosaves server setting is set +appropriately, the server will periodically save the game automatically (which can take a lot of disk space +in some cases); the frequency is controlled by the :literal:`saveturns` setting. In any case, you should +check the ownership, permissions, and disk space/quota for the directory or partition you're trying to save +to. + +Where are the save games located by default? +-------------------------------------------- + +On Unix like systems (e.g. Linux), they will be in :file:`~/.local/share/freeciv21/saves`. On Windows, they +are typically found in in the :file:`Appdata\\Roaming` User profile directory. For example: + +.. code-block:: rst + + C:\Users\MyUserName\AppData\Roaming\freeciv21\saves + + +You could change this by setting the :literal:`HOME` environment variable, or using the :literal:`--saves` +command line argument to the server (you would have to run it separately). + +How do I find out about the available units, improvements, terrain types, and technologies? +------------------------------------------------------------------------------------------- + +There is extensive help on this in the Help menu, but only once the game has been started - this is because +all of these things are configurable up to that point. + +The game comes with an interactive tutorial scenario. To run it, select :guilabel:`Start Scenario Game` from +the main menu, then load the tutorial scenario. + +How do I enable/disable sound support? +-------------------------------------- + +The client can be started without sound by supplying the commandline arguments :literal:`-P none`. The +default sound plugin can also be configured in the client settings. + +If the client was compiled with sound support, it will be enabled by default. + +Further instructions are in :file:`./doc/README.sound` in the source tarball. + +If sound does not work, try: + +.. code-block:: rst + + freeciv21-client -d 3 -P SDL -S stdsounds + + +This will help you get some debug information, which might give a clue why the sound does not work. + +What are the system requirements? +--------------------------------- + +Memory + +In a typical game the server takes about 30MB of memory and the client needs about 200MB. These values may +change with larger maps or tilesets. For a single player game you need to run both the client and the server. + +Processor + +We recommend at least a 200MHz processor. The server is almost entirely single-threaded, so more cores will +not help. If you find your game running too slow, these may be the reasons: + +Too little memory + Swapping memory pages on disc (virtual memory) is really slow. Look at the memory requirements above. + +Large map + Larger map doesn't necessary mean a more challenging or enjoyable game. You may try a smaller map. + +Many AI players + Again, having more players doesn't necessary mean a more challenging or enjoyable game. + +City Governor (CMA) + This is a really useful client side agent which helps you to organize our citizens. However, it consumes + many CPU cycles. + +Maps and compression + Creating map images and/or the compression of saved games for each turn will slow down new turns. + Consider using no compression. + +Graphic display + The client works well on 1024x800 or higher resolutions. On smaller screens you may want to enable + the Arrange widgets for small displays option under Interface tab in local options. + +Network + Any modern internet connection will suffice to play Freeciv21. Even mobile hotspots provide enough bandwidth. + +Windows +======= + +How do I use Freeciv21 under MS Windows? +---------------------------------------- + +Precompiled binaries can be downloaded from https://github.com/longturn/freeciv21/releases. The native +Windows packages come as self-extracting installers. + +OK, I've downloaded and installed it, how do I run it? +------------------------------------------------------ + +See the document about :doc:`windows-install` + +How do I use a different tileset? +--------------------------------- + +If the tilesets supplied with Freeciv21 don't do it for you, some popular add-on tilesets are available +through the :strong:`Freeciv21 Modpack Installer` utility. To install these, just launch the installer from +the Start menu, and choose the one you want; it should then be automatically downloaded and made available +for the current user. + +If the tileset you want is not available via the modpack installer, you'll have to install it by hand from +somewhere. To do that is beyond the scope of this FAQ. + +How do I use a different ruleset? +--------------------------------- + +Again, this is easiest if the ruleset is available through the :strong:`Freeciv21 Modpack Installer` utility +that's shipped with Freeciv21. + +If the ruleset you want is not available via the modpack installer, you'll have to install it by hand from +somewhere. To do that is beyond the scope of this FAQ. + +I opened a ruleset file in Notepad and it is very hard to read +-------------------------------------------------------------- + +The ruleset files (and other configuration files) are stored with UNIX line endings which Notepad doesn't +handle correctly. Please use an alternative editor like WordPad, notepad2, or notepad++ instead. + +Mac OS X +======== + +None of the current development team use the Mac OS. We're not building official packages, and don't +have recent experience. + +.. |reg| unicode:: U+000AE .. REGISTERED SIGN diff --git a/docs/General/index.rst b/docs/General/index.rst new file mode 100644 index 0000000000..28a66fa368 --- /dev/null +++ b/docs/General/index.rst @@ -0,0 +1,15 @@ +General +******* + +General + The General category is a catch-all for content that does not neatly fit into the other three. Things like + the FAQ and installation instructions go here. + + +.. toctree:: + faq.rst + install.rst + windows-install.rst + modpack-installer.rst + :maxdepth: 1 + diff --git a/docs/install/install.rst b/docs/General/install.rst similarity index 94% rename from docs/install/install.rst rename to docs/General/install.rst index 60001b79de..5edda2e248 100644 --- a/docs/install/install.rst +++ b/docs/General/install.rst @@ -1,8 +1,8 @@ Linux Compiling and Installing -============================== +****************************** General Prerequisites -********************* +===================== Freeciv21 has a number of prerequisites. Note, that apart from the first prerequisite, the Freeciv21 configuration process is smart enough to work out whether your system is suitable. If in doubt, just try it. @@ -75,8 +75,8 @@ Python Freeciv21 requires version 3 of Python -Prerequisites for the client and tools -************************************** +Prerequisites for the Client and Tools +====================================== The Freeciv21 project maintains a single Qt client. @@ -92,7 +92,7 @@ QT Libraries Obtaining the Source Code -************************* +========================= In order to compile Freeciv21, you need a local copy of the source code. You can download a saved version of the code from the project releases page at https://github.com/longturn/freeciv21/releases. Alternately you @@ -104,7 +104,7 @@ can get the latest from the master branch with the :file:`git` program with this Configuring -*********** +=========== Configuring Freeciv21 for compilation requires the use of the :file:`cmake` program. To build with defaults enter the following commmand from the freeciv21 directory: @@ -155,7 +155,7 @@ Once the command line directives are determined, the appropriate command looks l Compiling/Building -****************** +================== Once the build files have been written, then compile with this command: @@ -165,7 +165,7 @@ Once the build files have been written, then compile with this command: Installing -********** +========== Once the compilation is complete, install the game with this command. @@ -179,7 +179,7 @@ Once the compilation is complete, install the game with this command. Debian Linux Notes -****************** +================== Below are all the command line steps needed to start with a fresh install of Debian or its variants (e.g. Ubuntu, Linux Mint) to install Freeciv21. @@ -218,7 +218,7 @@ At this point follow the steps in the configuring_ section above. Windows Notes -************* +============= Msys2 is an available environment for compiling Freeciv21. Microsoft Windows Visual C is under development. @@ -237,7 +237,7 @@ Instead of installing, use this command to create the Windows Installer package: When the Ninja command is finished running, you will find an installer in :file:`build/Windows-${arch}` Documentation Build Notes -************************* +========================= Freeciv21 uses :file:`python3-sphynx` and https://readthedocs.org/ to generate well formatted HTML documentation. To generate a local copy of the documentation from the :file:`docs` directory you need two diff --git a/docs/General/modpack-installer.rst b/docs/General/modpack-installer.rst new file mode 100644 index 0000000000..d8f20255ee --- /dev/null +++ b/docs/General/modpack-installer.rst @@ -0,0 +1,106 @@ +Using the Modpack Installer Utility +*********************************** + +Installing Modpacks +=================== + +The modpack installer is a simple tool to download custom Freeciv21 content called :strong:`modpacks` from +the Internet, and automatically install them into the correct location to be used by the Freeciv21 client and +server. + +A :strong:`modpack` can consist of one or more of: + +* :strong:`rulesets` for game rules +* :strong:`scenarios` for game maps (with or without players/cities/etc) +* :strong:`tilesets` for game graphics +* :strong:`soundsets` or :strong:`musicsets` for sound effects and in-game music + +They can be installed using the modpack installer tool :file:`freeciv21-modpack-qt` that comes with the +standard installation. There is also a command-line-only tool called :file:`freeciv21-modpack`, which is +mainly useful for headless game servers. + +In standard Freeciv21 builds, when you start the graphical modpack installer, it will show a list of +modpacks curated by the Freeciv21 developers and longturn.net community. You can select one and click +:guilabel:`Install modpack`; the tool will download the files for the selected modpack, and any other +modpacks it depends on, and install them ready for the main Freeciv21 programs to use. + +.. image:: ../_static/images/gui-elements/modpack-installer.png + :align: center + :alt: Freeciv21 Modpack Installer Qt GUI application + +You can also point the installer at modpacks or lists on other servers: + +* If someone has given you an individual modpack URL (ending in :literal:`.json`), you can paste it into the + :guilabel:`Modpack URL` box, and when you click :guilabel:`Install modpack`, the modpack will immediately + downloaded and install. + +.. note:: If you have been given a URL ending up :literal:`.modpack` or :literal:`.mpdl`, + that is probably for legacy Freeciv and not Freeciv21. + +* If someone has given you a URL for a list of modpacks (also ending in :literal:`.json`) and you want to + browse them with the standard Freeciv21 modpack installer build, you need to start the tool with that URL + on its command line, for instance: + +.. code-block:: rst + + freeciv21-modpack --List https://example.com/3.1/my-modpacks.json + + +.. note:: The capital letter in :literal:`--List` + + The tool has some other command-line options, but most users will not need to use them. Use + :literal:`--help` for a list of them. + +Once you have installed a modpack, how you use it depends on the modpack type: + +* Scenarios (maps) should be listed under :guilabel:`Start scenario game` from the client start page, or + from the game server prompt via :literal:`/list scenarios`. + +.. tip:: For network play, scenarios need only be installed on the game server. + +* Rulesets should appear on the :guilabel:`Ruleset` drop-down from the client's :guilabel:`Start new game` + page. On the game server, you can load a ruleset with :literal:`/read ` or failing that perhaps + :literal:`/rulesetdir `. + +* Tilesets should appear for selection in the local client options, in the appropriate topology-specific + :guilabel:`Tileset` drop-down under :guilabel:`Graphics`. + +.. note:: Tilesets should be installed on the client machine. + +* Soundsets and musicsets should appear in the dropdowns on the :guilabel:`Sound` page of the local + client options. + +With standard Freeciv21 builds, modpacks get installed into a per-user area, not into the main Freeciv21 +installation. So you shouldn't need any special permissions to download them, and if you uninstall the +Freeciv21 game, any modpacks you downloaded are likely to remain on your system. Conversely, if you delete +downloaded modpacks by hand, the standard rulesets, tilesets, etc. supplied with Freeciv21 won't be touched. + +The precise location where files are downloaded to depends on your build and platform. For Unix systems, it +is likely to be under the hidden :file:`~/.local/share/freeciv21` directory in your home directory. For +Windows based sytems it will be in your user profile directory in a hidden :literal:`AppData` folder, +typically, :file:`C:\\Users\\[MyUserName]\\AppData\\Roaming\\Freeciv21` It is likely to be near where the +Freeciv21 client stores its saved games. + +Most modpacks are specific to a particular major version of Freeciv21; for instance, while a 3.0 ruleset or +tileset can be used with all Freeciv21 3.0.x releases, it cannot be used as-is with any 3.1.x release. So, +most modpacks are installed in a specific directory for the major version, such as +:file:`~/.local/share/freeciv21/3.1/` on Unix. + +.. note:: The modpack installer displays which version it will install for at the top of its window. + +An exception to this is scenario maps; scenarios created for one version of Freeciv21 can usually be loaded +in later versions, so they are installed in a version-independent location (typically +:file:`~/.local/share/freeciv21/scenarios/` on Unix). + +Once a modpack is installed, there is no uninstall action, and if you remove the files by hand, the +installer will still consider the modpack to be installed; the installer maintains its own database +(:file:`.control/modpacks.db`) listing which modpack versions are installed, but does not keep track of +which files were installed by which modpack. If the database gets out of sync with reality (or is deleted), +it's harmless for already installed modpacks and the main Freeciv21 programs (which do not consult the +database), but can confuse the modpack installer's dependency tracking later. + +Modpacks consist mostly of data files read by the Freeciv21 engine; they do not contain compiled binary code +(and are thus platform-independent). Rulesets can contain code in the form of Lua scripts, but this is +executed in a sandbox to prevent obvious security exploits. Modpacks are installed to a specific area and +cannot overwrite arbitrary files on your system. Nevertheless, you should only install modpacks from sources +you trust. diff --git a/docs/install/windows-install.rst b/docs/General/windows-install.rst similarity index 80% rename from docs/install/windows-install.rst rename to docs/General/windows-install.rst index aa841a91a1..725aa023b2 100644 --- a/docs/install/windows-install.rst +++ b/docs/General/windows-install.rst @@ -1,5 +1,5 @@ Windows Installation -==================== +******************** The Freeciv21 community provides a Microsoft Windows\ |reg| installer when new releases are tagged. The following is instructions for installing on Windows. @@ -11,7 +11,7 @@ download and double-click the file to run. .. _admin: Local Admin Installation -************************ +======================== The following steps assume you :emphasis:`are` logged on as a local Administrator. If you :emphasis:`are not` then jump to the non-admin_ section below. @@ -22,14 +22,14 @@ Click :guilabel:`Yes` and the following panel will load after an uncompress proc Click :guilabel:`Next` to continue... -.. image:: ../_static/nsis-installer/01-Welcome.png +.. image:: ../_static/images/windows-installer/01-Welcome.png :align: center :height: 400 :alt: Welcome Panel Check the box to accept the GNU 3.0 License and then click :guilabel:`Next` to continue... -.. image:: ../_static/nsis-installer/02-License.png +.. image:: ../_static/images/windows-installer/02-License.png :align: center :height: 400 :alt: GNU License Acceptenace Panel @@ -37,14 +37,14 @@ Check the box to accept the GNU 3.0 License and then click :guilabel:`Next` to c By default, the installer only installs the client, server and modpack installer. If you want other utilities, you will need to pick them from the list. Click :guilabel:`Next` to continue... -.. image:: ../_static/nsis-installer/03-Components.png +.. image:: ../_static/images/windows-installer/03-Components.png :align: center :height: 400 :alt: Select Components Panel Select the installation type and then click :guilabel:`Next` to continue... -.. image:: ../_static/nsis-installer/04-Admin-Multi-User.png +.. image:: ../_static/images/windows-installer/04-Admin-Multi-User.png :align: center :height: 400 :alt: Admin Installation Panel @@ -52,14 +52,14 @@ Select the installation type and then click :guilabel:`Next` to continue... By default, the Admin installer will place the files in the :file:`C:\\Program Files` folder. Change if you want and click :guilabel:`Next` to continue... -.. image:: ../_static/nsis-installer/05a-Admin-Folder.png +.. image:: ../_static/images/windows-installer/05a-Admin-Folder.png :align: center :height: 400 :alt: Admin Instalation Folder Panel This panel shows the files being installed. No action is needed. -.. image:: ../_static/nsis-installer/06-Copy-Files.png +.. image:: ../_static/images/windows-installer/06-Copy-Files.png :align: center :height: 400 :alt: Copying Files Panel @@ -67,7 +67,7 @@ This panel shows the files being installed. No action is needed. If you want to run Freeciv21 right away, leave the box checked and click :guilabel:`Finish`. Otherwise, uncheck the box before clicking :guilabel:`Finish` to complete the installation. -.. image:: ../_static/nsis-installer/07-Finish.png +.. image:: ../_static/images/windows-installer/07-Finish.png :align: center :height: 400 :alt: Finish Panel @@ -78,21 +78,21 @@ Freeciv21 [Version] --> Freeciv21 Client`. .. _non-admin: Non-Local Admin (Unpriviledged User) Instalation -************************************************ +================================================ If you :emphasis:`are not` logged on as a local Administrator there is no UAC prompt and the following panel will load after an uncompress process has completed. Click :guilabel:`Next` to continue... -.. image:: ../_static/nsis-installer/01-Welcome.png +.. image:: ../_static/images/windows-installer/01-Welcome.png :align: center :height: 400 :alt: Welcome Panel Check the box to accept the GNU 3.0 License and then click :guilabel:`Next` to continue... -.. image:: ../_static/nsis-installer/02-License.png +.. image:: ../_static/images/windows-installer/02-License.png :align: center :height: 400 :alt: GNU License Acceptenace Panel @@ -100,7 +100,7 @@ Check the box to accept the GNU 3.0 License and then click :guilabel:`Next` to c By default, the installer only installs the client, server and modpack installer. If you want other utilities, you will need to pick them from the list. Click :guilabel:`Next` to continue... -.. image:: ../_static/nsis-installer/03-Components.png +.. image:: ../_static/images/windows-installer/03-Components.png :align: center :height: 400 :alt: Select Components Panel @@ -108,14 +108,14 @@ utilities, you will need to pick them from the list. Click :guilabel:`Next` to c The Non-Admin Installer places the files in your User Directory by default. Change if you want and click :guilabel:`Next` to continue... -.. image:: ../_static/nsis-installer/05b-User-Folder.png +.. image:: ../_static/images/windows-installer/05b-User-Folder.png :align: center :height: 400 :alt: User Instalation Folder Panel This panel shows the files being installed. No action is needed. -.. image:: ../_static/nsis-installer/06-Copy-Files.png +.. image:: ../_static/images/windows-installer/06-Copy-Files.png :align: center :height: 400 :alt: Copying Files Panel @@ -123,7 +123,7 @@ This panel shows the files being installed. No action is needed. If you want to run Freeciv21 right away, leave the box checked and click :guilabel:`Finish`. Otherwise, uncheck the box before clicking :guilabel:`Finish` to complete the installation. -.. image:: ../_static/nsis-installer/07-Finish.png +.. image:: ../_static/images/windows-installer/07-Finish.png :align: center :height: 400 :alt: Finish Panel diff --git a/docs/rulesets/effects.rst b/docs/Modding/Rulesets/effects.rst similarity index 52% rename from docs/rulesets/effects.rst rename to docs/Modding/Rulesets/effects.rst index 4a01719e16..7d025c4df9 100644 --- a/docs/rulesets/effects.rst +++ b/docs/Modding/Rulesets/effects.rst @@ -1,57 +1,51 @@ Effects -======= - -The ``effects.ruleset`` file contains all effects in play in a Freeciv21 ruleset. -They have the following form (this is perhaps the most complicated example I -could find):: - - [effect_hydro_plant] - type = "Output_Bonus" - value = 25 - reqs = - { "type", "name", "range", "present", "quiet" - "Building", "Factory", "City", TRUE, FALSE - "Building", "Hydro Plant", "City", TRUE, FALSE - "OutputType", "Shield", "Local", TRUE, TRUE - "Building", "Hoover Dam", "Player", FALSE, FALSE - "Building", "Nuclear Plant", "City", FALSE, FALSE - } - -The text in the brackets is the entry name, which just has to be unique, but -is otherwise not used. The ``type`` field tells Freeciv21 which effect you are -defining. The ``value`` is the effect's value, which depends on which effect it -is. The ``reqs`` table contain a list of requirements for this effect being in -effect. You need to satisfy all requirements listed here for this effect to -take effect in the game. Requirements with ``present = TRUE`` must be present, -those with ``present = FALSE`` must not be present. - -Value is integral amount parameter for many effects (must be in the range --32767 to 32767). - -Requirement range may be one of: ``None``, ``Local``, ``CAdjacent`` (Cardinally -Adjacent), ``Adjacent``, ``City``, ``Continent``, ``Player``, ``Allied``, -``World``. Some requirement types may only work at certain ranges; this is -described below. In particular, at present, ``Continent`` effects can affect -only cities and units in cities. - -A requirement may have a ``survives`` field, and if this ``TRUE``, the effect -survives destruction. This is supported for only a few conditions and ranges: -wonders (at world or player range), nations, and advances (both at world range -only). - -A requirement may have a ``present`` field, and if this is ``FALSE``, -the requirement is negated (the condition must not be true for the req to be -met). - -A requirement may have a ``quiet`` field, and if this is ``TRUE``, the help -system does not try to autogenerate text about that requirement. This can be -used if the help system's text is unclear or misleading, or if you want to -describe the requirement in your own words. The ``quiet`` field has no effect on -the game rules. +******* + +The ``effects.ruleset`` file contains all effects in play in a Freeciv21 ruleset. They have the following +form (this is perhaps the most complicated example I could find): + +.. code-block:: rst + + [effect_hydro_plant] + type = "Output_Bonus" + value = 25 + reqs = + { "type", "name", "range", "present", "quiet" + "Building", "Factory", "City", TRUE, FALSE + "Building", "Hydro Plant", "City", TRUE, FALSE + "OutputType", "Shield", "Local", TRUE, TRUE + "Building", "Hoover Dam", "Player", FALSE, FALSE + "Building", "Nuclear Plant", "City", FALSE, FALSE + } + +The text in the brackets is the entry name, which just has to be unique, but is otherwise not used. The +``type`` field tells Freeciv21 which effect you are defining. The ``value`` is the effect's value, which +depends on which effect it is. The ``reqs`` table contain a list of requirements for this effect being in +effect. You need to satisfy all requirements listed here for this effect to take effect in the game. +Requirements with ``present = TRUE`` must be present, those with ``present = FALSE`` must not be present. + +Value is integral amount parameter for many effects (must be in the range -32767 to 32767). + +Requirement range may be one of: ``None``, ``Local``, ``CAdjacent`` (Cardinally Adjacent), ``Adjacent``, +``City``, ``Continent``, ``Player``, ``Allied``, ``World``. Some requirement types may only work at certain +ranges; this is described below. In particular, at present, ``Continent`` effects can affect only cities and +units in cities. + +A requirement may have a ``survives`` field, and if this ``TRUE``, the effect survives destruction. This is +supported for only a few conditions and ranges: wonders (at world or player range), nations, and advances +(both at world range only). + +A requirement may have a ``present`` field, and if this is ``FALSE``, the requirement is negated (the +condition must not be true for the req to be met). + +A requirement may have a ``quiet`` field, and if this is ``TRUE``, the help system does not try to +autogenerate text about that requirement. This can be used if the help system's text is unclear or +misleading, or if you want to describe the requirement in your own words. The ``quiet`` field has no effect +on the game rules. Requirement types and supported ranges --------------------------------------- +====================================== ==================== ================ Requirement Supported ranges @@ -105,59 +99,53 @@ Requirement Supported ranges ``MinHitPoints`` ``Local`` ==================== ================ -MinSize is the minimum size of a city required. -AI is ai player difficulty level. -TerrainClass is either "Land" or "Oceanic". -CityTile is either "Center" (city center) or "Claimed" (owned). -CityStatus is "OwnedByOriginal" -DiplRel is a diplomatic relationship. -MaxUnitsOnTile is about the number of units present on a tile. -UnitState is "Transported", "Transporting", "OnNativeTile", "OnLivableTile", -"InNativeExtra", "OnDomesticTile", "MovedThisTurn" or "HasHomeCity". -Activity is "Idle", "Pollution", "Mine", "Irrigate", "Fortified", "Fortress", "Sentry", -"Pillage", "Goto", "Explore", "Transform", "Fortifying", "Fallout", "Base", "Road", -"Convert", "Cultivate", or "Plant". -MinMoveFrags is the minimum move fragments the unit must have left. -MinCalFrag is the minimum sub-year division the calendar must have reached, -if enabled (see [calendar].fragments in game.ruleset). -Nationality is fulfilled by any citizens of the given nationality -present in the city. -ServerSetting is if a Boolean server setting is enabled. The setting must be -visible to all players and affect the game rules. +* MinSize is the minimum size of a city required. +* AI is ai player difficulty level. +* TerrainClass is either "Land" or "Oceanic". +* CityTile is either "Center" (city center) or "Claimed" (owned). +* CityStatus is "OwnedByOriginal" +* DiplRel is a diplomatic relationship. +* MaxUnitsOnTile is about the number of units present on a tile. +* UnitState is "Transported", "Transporting", "OnNativeTile", "OnLivableTile", "InNativeExtra", + "OnDomesticTile", "MovedThisTurn" or "HasHomeCity". +* Activity is "Idle", "Pollution", "Mine", "Irrigate", "Fortified", "Fortress", "Sentry", "Pillage", + "Goto", "Explore", "Transform", "Fortifying", "Fallout", "Base", "Road", "Convert", "Cultivate", or "Plant". +* MinMoveFrags is the minimum move fragments the unit must have left. +* MinCalFrag is the minimum sub-year division the calendar must have reached, if enabled (see + [calendar].fragments in game.ruleset). +* Nationality is fulfilled by any citizens of the given nationality present in the city. +* ServerSetting is if a Boolean server setting is enabled. The setting must be visible to all players and + affect the game rules. Details about requirement types -------------------------------- +=============================== The DiplRel requirement type -............................ - -Look for the diplomatic relationship "Never met", "War", "Cease-fire", -"Armistice", "Peace", "Alliance", "Team", "Gives shared vision", -"Receives shared vision", "Hosts embassy", "Has embassy", -"Hosts real embassy" (not from an effect), "Has real embassy", -"Has Casus Belli" (reason for war), "Provided Casus Belli" or "Is foreign". - -A DiplRel is considered fulfilled for the range - * world if some player in the world has the specified diplomatic - relationship to some other living player. - * player if the player has the specified diplomatic relationship to some - other living player. - * local if the first player has the specified relationship to the second - player. Example: When testing a build requirement for an extra the first - player is the owner of the unit and the second player the owner of the - terrain the extra is built on. - -Only the exact relationship required fulfills it. Example: An alliance or -an armistice agreement won't fulfill a "Peace" requirement. - -It is possible to create a requirement that in some situations won't have a -player to check. In those cases the requirement will always be considered -unfulfilled. This applies to both present and not present requirements. The -ranges Alliance, Team, Player and Local needs a player. The Local range also -needs the player the first player's relationship is to. - -Example: The requirements below are about the relationship to the owner of a -tile. The table shows in what situations a requirement is fulfilled. +---------------------------- + +Look for the diplomatic relationship "Never met", "War", "Cease-fire", "Armistice", "Peace", "Alliance", +"Team", "Gives shared vision", "Receives shared vision", "Hosts embassy", "Has embassy", "Hosts real +embassy" (not from an effect), "Has real embassy", "Has Casus Belli" (reason for war), "Provided Casus +Belli" or "Is foreign". + +A DiplRel is considered fulfilled for the range: + +* world if some player in the world has the specified diplomatic relationship to some other living player. +* player if the player has the specified diplomatic relationship to some other living player. +* local if the first player has the specified relationship to the second player. Example: When testing a + build requirement for an extra the first player is the owner of the unit and the second player the owner + of the terrain the extra is built on. + +Only the exact relationship required fulfills it. Example: An alliance or an armistice agreement won't +fulfill a "Peace" requirement. + +It is possible to create a requirement that in some situations won't have a player to check. In those cases +the requirement will always be considered unfulfilled. This applies to both present and not present +requirements. The ranges Alliance, Team, Player and Local needs a player. The Local range also needs the +player the first player's relationship is to. + +Example: The requirements below are about the relationship to the owner of a tile. The table shows in what +situations a requirement is fulfilled. +---------------------------------------------+----------+-----------+---------+ | | Fulfilled when the tile is | @@ -170,17 +158,16 @@ tile. The table shows in what situations a requirement is fulfilled. +---------------------------------------------+----------+-----------+---------+ The MaxUnitsOnTile requirement type -................................... +----------------------------------- -Check the number of units present on a tile. Is true if no more than the -specified number of units are present on a single tile. +Check the number of units present on a tile. Is true if no more than the specified number of units are +present on a single tile. -Hint: By using negation ("not present") it is possible to check if a tile -has more than the given numbers. It is possible to combine a negated and a -non negated requirement to specify a range. +.. tip:: By using negation ("not present") it is possible to check if a tile has more than the given numbers. + It is possible to combine a negated and a non negated requirement to specify a range. The UnitState requirement type -.............................. +------------------------------ Transported is fulfilled if the unit is transported by another unit. @@ -189,12 +176,11 @@ Transporting is fulfilled if the unit is transporting another unit. OnNativeTile - is fulfilled if the unit is on a tile with native terrain or with a native - Extra. Doesn't care about details like cities and safe tiles. + is fulfilled if the unit is on a tile with native terrain or with a native Extra. Doesn't care about + details like cities and safe tiles. OnLivableTile - is fulfilled if the unit is on a tile where it can exist outside of a - transport. + is fulfilled if the unit is on a tile where it can exist outside of a transport. InNativeExtra is fulfilled if the unit is on a tile with an extra native to it. @@ -212,31 +198,28 @@ Effect types ------------ Tech_Parasite - Gain any advance known already by amount number of other teams, - if team_pooled_research is enabled, or amount number of other players - otherwise. Note that if you have two such effects, they combine into - one much worse effect (the number of players required to gain an advance - is increased). + Gain any advance known already by amount number of other teams, if team_pooled_research is enabled, + or amount number of other players otherwise. + +.. note:: If you have two such effects, they combine into one much worse effect (the number of players + required to gain an advance is increased). Airlift - Allow airlift to/from a city. The value tells how many units per - turn can be airlifted, unless server setting 'airlifttingstyle' sets - the number unlimited for either source or destination city. If airlifts - are set to unlimited, they are enabled by any positive value of this - effect. + Allow airlift to/from a city. The value tells how many units per turn can be airlifted, unless server + setting 'airlifttingstyle' sets the number unlimited for either source or destination city. If airlifts + are set to unlimited, they are enabled by any positive value of this effect. Any_Government Allow changing to any form of government regardless of tech prerequisites. Capital_City - The city with positive value is a capital city. Player's city with highest - Capital_City value (or random among those with equal positive value) is - the primary capital. Cities with lesser positive value are secondary - capitals. + The city with positive value is a capital city. Player's city with highest Capital_City value (or + random among those with equal positive value) is the primary capital. Cities with lesser positive value + are secondary capitals. Gov_Center - The city with this effect is governmental center. Corruption and - waste depends on distance to nearest such city. + The city with this effect is governmental center. Corruption and waste depends on distance to nearest + such city. Enable_Nuke Allows the production of nuclear weapons. @@ -245,15 +228,13 @@ Enable_Space Allows the production of space components. Specialist_Output - Specify what outputs a specialist is producing. Should be used with an - OutputType requirement. + Specify what outputs a specialist is producing. Should be used with an OutputType requirement. Output_Bonus City production is increased by amount percent. Output_Bonus_2 - City production is increased by amount percent after Output_Bonus, so is - multiplicative with it. + City production is increased by amount percent after Output_Bonus, so is multiplicative with it. Output_Add_Tile Add amount to each worked tile. @@ -265,76 +246,72 @@ Output_Per_Tile Increase tile output by amount percent. Output_Tile_Punish_Pct - Reduce the output of a tile by amount percent. The number of units to - remove is rounded down. Applied after everything except a city center's - minimal output. + Reduce the output of a tile by amount percent. The number of units to remove is rounded down. Applied + after everything except a city center's minimal output. Output_Waste_Pct Reduce waste by amount percent. Force_Content - Make amount' unhappy citizens content. Applied after martial law and unit - penalties. + Make amount' unhappy citizens content. Applied after martial law and unit penalties. Give_Imm_Tech Give amount techs immediately. Conquest_Tech_Pct - Percent chance that a player conquering a city learns a tech from the - former owner. + Percent chance that a player conquering a city learns a tech from the former owner. Growth_Food - Food left after cities grow or shrink is amount percent of the capacity of - the city's foodbox. This also affects the 'aqueductloss' penalty. + Food left after cities grow or shrink is amount percent of the capacity of he city's foodbox. This also + affects the 'aqueductloss' penalty. Have_Contact If value > 0, gives contact to all the other players. Have_Embassies - If value > 0, gives an embassy with all the other players owner has ever - had contact with. + If value > 0, gives an embassy with all the other players owner has ever had contact with. Irrigation_Pct - The tile gets value % of its terrain's irrigation_food_incr bonus. - (This is how irrigation-like extras have an effect.) + The tile gets value % of its terrain's irrigation_food_incr bonus. + +.. note:: This is how irrigation-like extras have an effect. Mining_Pct The tile gets value % of its terrain's mining_shield_incr bonus. - (This is how mine-like extras have an effect.) + + +.. note:: This is how mine-like extras have an effect. Make_Content - Make amount unhappy citizens content. Applied before martial law and unit - penalties. + Make amount unhappy citizens content. Applied before martial law and unit penalties. Make_Content_Mil Make amount unhappy citizens caused by units outside of a city content. Make_Content_Mil_Per - Make amount per unit of unhappy citizens caused by units outside of a city - content. + Make amount per unit of unhappy citizens caused by units outside of a city content. Make_Happy Make amount citizens happy. Enemy_Citizen_Unhappy_Pct - There will be one extra unhappy citizen for each value/100 citizens - of enemy nationality in the city. + There will be one extra unhappy citizen for each value/100 citizens of enemy nationality in the city. No_Anarchy - No period of anarchy between government changes. (This also neuters - the Has_Senate effect.) + No period of anarchy between government changes. + +.. note:: This also neuters the Has_Senate effect. Nuke_Proof City is nuke proof. Pollu_Pop_Pct - Increases pollution caused by each unit of population by amount - percent (adds to baseline of 100%, i.e. 1 pollution per citizen). + Increases pollution caused by each unit of population by amount percent (adds to baseline of 100%, + i.e. 1 pollution per citizen). Pollu_Pop_Pct_2 - Increases pollution caused by each unit of population by amount - percent (adds to baseline of 100%, i.e. 1 pollution per citizen). - This factor is applied after Pollu_Pop_Pct, so is multiplicative with it. + Increases pollution caused by each unit of population by amount percent (adds to baseline of 100%, + i.e. 1 pollution per citizen). This factor is applied after Pollu_Pop_Pct, so is multiplicative with it. Pollu_Prod_Pct Increases pollution caused by shields by amount percent. @@ -349,98 +326,79 @@ Reveal_Map Immediately make entire map known. Border_Vision - Give vision on all tiles within the player's borders. Happens during - turn change. - Does nothing unless the borders setting is set to "Enabled". You can - lock it if border vision rules are important to your ruleset. + Give vision on all tiles within the player's borders. Happens during turn change. Does nothing unless the + borders setting is set to "Enabled". You can lock it if border vision rules are important to your ruleset. Incite_Cost_Pct Increases revolt cost by amount percent. Unit_Bribe_Cost_Pct - Increases unit bribe cost by amount percent. Requirements are from the - point of view of the target unit, not the briber. + Increases unit bribe cost by amount percent. Requirements are from the point of view of the target unit, + not the briber. Max_Stolen_Gold_Pm - The upper limit on the permille of the players gold that may be - stolen by a unit doing the "Steal Gold" and the "Steal Gold Escape" - actions. Evaluated against the city stolen from. + The upper limit on the permille of the players gold that may be stolen by a unit doing the "Steal Gold" + and the "Steal Gold Escape" actions. Evaluated against the city stolen from. Thiefs_Share_Pm - The permille of the gold stolen by a unit doing the "Steal Gold" and the - "Steal Gold Escape" actions that is lost before it reaches the player - ordering it. Evaluated against the actor unit. + The permille of the gold stolen by a unit doing the "Steal Gold" and the "Steal Gold Escape" actions + that is lost before it reaches the player ordering it. Evaluated against the actor unit. Maps_Stolen_Pct - The probability (in percent) that the map of a tile is stolen in the - actions "Steal Maps" and "Steal Maps Escape". - DiplRel reqs are unit owner to city owner. - Requirements evaluated against tile or city not supported. - Default value: 100% + The probability (in percent) that the map of a tile is stolen in the actions "Steal Maps" and "Steal Maps + Escape". DiplRel reqs are unit owner to city owner. Requirements evaluated against tile or city not + supported. Default value: 100% Illegal_Action_Move_Cost - The number of move fragments lost when the player tries to do an action - that turns out to be illegal. Only applied when the player wasn't aware that - the action was illegal and its illegality therefore reveals new information. + The number of move fragments lost when the player tries to do an action that turns out to be illegal. + Only applied when the player wasn't aware that the action was illegal and its illegality therefore + reveals new information. Illegal_Action_HP_Cost - The number of hit points lost when the player tries to do an action - that turns out to be illegal. Only applied when the player wasn't aware that - the action was illegal and its illegality therefore reveals new information. - Can kill the unit. - If the action always causes the actor unit to end up at the target tile two - consolation prizes are given. An area with the radius of the actor unit's - vision_radius_sq tiles is revealed. The player may also get contact with the - owners of units and cites adjacent to the target tile. + The number of hit points lost when the player tries to do an action that turns out to be illegal. Only + applied when the player wasn't aware that the action was illegal and its illegality therefore reveals new + information. Can kill the unit. If the action always causes the actor unit to end up at the target tile + two consolation prizes are given. An area with the radius of the actor unit's vision_radius_sq tiles is + revealed. The player may also get contact with the owners of units and cites adjacent to the target tile. Action_Success_Actor_Move_Cost - The number of move fragments lost when a unit successfully performs an - action. Evaluated and done after the action is successfully completed. Added - on top of any movement fragments the action itself subtracts. + The number of move fragments lost when a unit successfully performs an action. Evaluated and done after + the action is successfully completed. Added on top of any movement fragments the action itself subtracts. Action_Success_Target_Move_Cost - The number of move fragments subtracted from a unit when someone - successfully performs an action on it. Evaluated and done after the action - is successfully completed. Added on top of any movement fragments the - action itself subtracts. Only supported for actions that targets an - individual unit. (See doc/README.actions) + The number of move fragments subtracted from a unit when someone successfully performs an action on it. + Evaluated and done after the action is successfully completed. Added on top of any movement fragments the + action itself subtracts. Only supported for actions that targets an individual unit. + (See doc/README.actions) Casus_Belli_Caught - Checked when a player is caught trying to do an action. Will cause an - incident with the intended victim player if the value is 1 or higher. The - incident gives the intended victim a casus belli against the actor player. - A value of 1000 or higher is international outrage. International outrage - gives every other player a casus belli against the actor. + Checked when a player is caught trying to do an action. Will cause an incident with the intended victim + player if the value is 1 or higher. The incident gives the intended victim a casus belli against the + actor player. A value of 1000 or higher is international outrage. International outrage gives every other + player a casus belli against the actor. Casus_Belli_Success - Checked when a player does an action to another player. Will cause an - incident with the intended victim player if the value is 1 or higher. The - incident gives the intended victim a casus belli against the actor player. - A value of 1000 or higher is international outrage. International outrage - gives every other player a casus belli against the actor. + Checked when a player does an action to another player. Will cause an incident with the intended victim + player if the value is 1 or higher. The incident gives the intended victim a casus belli against the actor + player. A value of 1000 or higher is international outrage. International outrage gives every other player + a casus belli against the actor. Casus_Belli_Complete - Checked when a player completes an action that takes several turns - against another player. Will cause an incident with the intended victim - player if the value is 1 or higher. The incident gives the intended victim - a casus belli against the actor player. A value of 1000 or higher is - international outrage. International outrage gives every other player a - casus belli against the actor. - Only "Pillage" is currently supported. + Checked when a player completes an action that takes several turns against another player. Will cause an + incident with the intended victim player if the value is 1 or higher. The incident gives the intended + victim a casus belli against the actor player. A value of 1000 or higher is international outrage. + International outrage gives every other player a casus belli against the actor. Only "Pillage" is + currently supported. Action_Odds_Pct - Modifies the odds of an action being successful. Some actions have a - risk: the actor may get caught before he can perform it. This effect - modifies the actor's odds. A positive value helps him. A negative value - makes it more probable that he will get caught. Currently supports the - actions "Incite City", "Incite City Escape", "Steal Gold", - "Steal Gold Escape", "Steal Maps", "Steal Maps Escape", "Suitcase Nuke", - "Suitcase Nuke Escape", "Sabotage City", "Sabotage City Escape", - "Targeted Sabotage City", "Targeted Sabotage City Escape", - "Sabotage City Production", "Sabotage City Production Escape", - "Surgical Strike Building", "Surgical Strike Production", - "Steal Tech", "Steal Tech Escape Expected", "Targeted Steal Tech", - "Targeted Steal Tech Escape Expected" and "Spread Plague". + Modifies the odds of an action being successful. Some actions have a risk: the actor may get caught + before he can perform it. This effect modifies the actor's odds. A positive value helps him. A negative + value makes it more probable that he will get caught. Currently supports the actions "Incite City", + "Incite City Escape", "Steal Gold", "Steal Gold Escape", "Steal Maps", "Steal Maps Escape", "Suitcase + Nuke", "Suitcase Nuke Escape", "Sabotage City", "Sabotage City Escape", "Targeted Sabotage City", + "Targeted Sabotage City Escape", "Sabotage City Production", "Sabotage City Production Escape", + "Surgical Strike Building", "Surgical Strike Production", "Steal Tech", "Steal Tech Escape Expected", + "Targeted Steal Tech", "Targeted Steal Tech Escape Expected" and "Spread Plague". Size_Adj Increase maximum size of a city by amount. @@ -449,36 +407,31 @@ Size_Unlimit Make the size of a city unlimited. Unit_Slots - Number of unit slots city can have units in. New units cannot be built, - nor can homecity be changed so that maintained units would use more slots - than this. Single unit does not necessarily use single slot - that's defined - separately for each unit type. + Number of unit slots city can have units in. New units cannot be built, nor can homecity be changed so + that maintained units would use more slots than this. Single unit does not necessarily use single slot - + that's defined separately for each unit type. SS_Structural, SS_Component, SS_Module - A part of a spaceship; this is a "Local" ranged effect. It (for now) - applies to improvements which cannot be built unless "Enable_Space" is felt. - Buildings which have this effect should probably not be given any other - effects. + A part of a spaceship; this is a "Local" ranged effect. It (for now) applies to improvements which + cannot be built unless "Enable_Space" is felt. Buildings which have this effect should probably not be + given any other effects. Spy_Resistant - In diplomatic combat defending diplomatic units will get an AMOUNT - percent bonus. All Spy_Resistant's are summed before being applied. + In diplomatic combat defending diplomatic units will get an AMOUNT percent bonus. All Spy_Resistant's + are summed before being applied. Building_Saboteur_Resistant - If a spy specifies a target for sabotage, then she has an AMOUNT - percent chance to fail. + If a spy specifies a target for sabotage, then she has an AMOUNT percent chance to fail. Stealings_Ignore - When determining how difficult it is to steal a tech from enemy, AMOUNT - previous times tech has been stolen from the city is ignored. Negative amount - means that number of times tech has already been stolen from target city does - not affect current attempt at all. With this effect it's possible to allow - diplomats to steal tech multiple times from the same city, or make it easier - for spies. + When determining how difficult it is to steal a tech from enemy, AMOUNT previous times tech has been + stolen from the city is ignored. Negative amount means that number of times tech has already been stolen + from target city does not affect current attempt at all. With this effect it's possible to allow + diplomats to steal tech multiple times from the same city, or make it easier for spies. Move_Bonus - Add amount movement to units. Use UnitClass' requirement with range of - 'Local' to give it a specific class of units only. + Add amount movement to units. Use UnitClass' requirement with range of 'Local' to give it a specific + class of units only. Unit_No_Lose_Pop No population lost when a city's defender is lost. @@ -490,33 +443,28 @@ Upgrade_Unit Upgrade amount obsolete units per turn. Upkeep_Free - Improvements with amount or less upkeep cost become free to upkeep (others - are unaffected). + Improvements with amount or less upkeep cost become free to upkeep (others are unaffected). Tech_Upkeep_Free - If this value is greater than 0, the tech upkeep is reduced by this value. - For tech upkeep style "Basic" this is total reduction, for tech upkeep - style "Cities" this reduction is applied to every city. + If this value is greater than 0, the tech upkeep is reduced by this value. For tech upkeep style + "Basic" this is total reduction, for tech upkeep style "Cities" this reduction is applied to every city. No_Unhappy No citizens in the city are ever unhappy. Veteran_Build - Increases the veteran class of newly created units of this type. The - total amount determines the veteran class (clipped at the maximum for the - unit). + Increases the veteran class of newly created units of this type. The total amount determines the veteran + class (clipped at the maximum for the unit). Veteran_Combat - Increases the chance of units of this type becoming veteran after combat - by amount percent. + Increases the chance of units of this type becoming veteran after combat by amount percent. Combat_Rounds - Maximum number of rounds combat lasts. Unit is the attacker. Zero and - negative values mean that combat continues until either side dies. + Maximum number of rounds combat lasts. Unit is the attacker. Zero and negative values mean that combat + continues until either side dies. HP_Regen - Units that do not move recover amount percentage of their full hitpoints - per turn. + Units that do not move recover amount percentage of their full hitpoints per turn. City_Vision_Radius_Sq Increase city vision radius in squared distance by amount tiles. @@ -525,55 +473,47 @@ Unit_Vision_Radius_Sq Increase unit vision radius in squared distance by amount tiles. Defend_Bonus - Increases defensive bonuses of units. Any unit requirements on this effect - will be applied to the _attacking_ unit. Attackers with "BadWallAttacker" flag - will have their firepower set to 1. + Increases defensive bonuses of units. Any unit requirements on this effect will be applied to the + _attacking_ unit. Attackers with "BadWallAttacker" flag will have their firepower set to 1. Attack_Bonus - Increases offensive bonuses of units. Unit requirements on this effect are - the attacking unit itself. + Increases offensive bonuses of units. Unit requirements on this effect are the attacking unit itself. Fortify_Defense_Bonus - Percentage defense bonus multiplicative with Defend_Bonus, usually given - to fortified units. Unit requirements on this effect are the defending unit - itself. + Percentage defense bonus multiplicative with Defend_Bonus, usually given to fortified units. Unit + requirements on this effect are the defending unit itself. Gain_AI_Love Gain amount points of "AI love" with AI(s). Turn_Years - Year advances by AMOUNT each turn unless Slow_Down_Timeline causes it - to be less. + Year advances by AMOUNT each turn unless Slow_Down_Timeline causes it to be less. Turn_Fragments Year fragments advance by AMOUNT each turn. Slow_Down_Timeline - Slow down the timeline based on the AMOUNT. If AMOUNT >= 3 the timeline - will be max 1 year/turn; with AMOUNT == 2 it is max 2 years/turn; - with AMOUNT == 1 it is max 5 years/turn; with AMOUNT <= 0 the timeline is - unaffected. The effect will be ignored if game.spacerace isn't set. + Slow down the timeline based on the AMOUNT. If AMOUNT >= 3 the timeline will be max 1 year/turn; with + AMOUNT == 2 it is max 2 years/turn; with AMOUNT == 1 it is max 5 years/turn; with AMOUNT <= 0 the + timeline is unaffected. The effect will be ignored if game.spacerace isn't set. Civil_War_Chance - Base chance in per cent of a nation being split by civil war when its - capital is captured is increased by this amount. This percentage is in- - creased by 5 for each city in civil disorder and reduced by 5 for each one - celebrating. + Base chance in per cent of a nation being split by civil war when its capital is captured is increased + by this amount. This percentage is in- creased by 5 for each city in civil disorder and reduced by 5 for + each one celebrating. City_Unhappy_Size - The maximum number of citizens in each city that are naturally content; - in larger cities, new citizens above this limit start out unhappy. (Before - Empire_Size_Base/Step are applied.) + The maximum number of citizens in each city that are naturally content; in larger cities, new citizens + above this limit start out unhappy. (Before Empire_Size_Base/Step are applied.) Empire_Size_Base - Once your civilization has more cities than the value of this effect, - each city gets one more unhappy citizen. If the sum of this effect and - Empire_Size_Step is zero, there is no such penalty. + Once your civilization has more cities than the value of this effect, each city gets one more unhappy + citizen. If the sum of this effect and Empire_Size_Step is zero, there is no such penalty. Empire_Size_Step - After your civilization reaches Empire_Size_Base size, it gets one more - unhappy citizen for each amount of cities it gets above that. Set to zero to - disable. You can use Empire_Size_Step even if Empire_Size_Base is zero. + After your civilization reaches Empire_Size_Base size, it gets one more unhappy citizen for each amount + of cities it gets above that. Set to zero to disable. You can use Empire_Size_Step even if + Empire_Size_Base is zero. Max_Rates The maximum setting for each tax rate is amount. @@ -588,26 +528,22 @@ Rapture_Grow Can rapture grow cities. Revolution_Unhappiness - If value is greater than zero, it tells how many turns citizens - will tolerate city disorder before government falls. If value is - zero, government never falls. + If value is greater than zero, it tells how many turns citizens will tolerate city disorder before + government falls. If value is zero, government never falls. Has_Senate Has a senate that prevents declarations of war in most cases. Inspire_Partisans - Partisan units (defined in units.ruleset) may spring up when this player's - cities are taken. + Partisan units (defined in units.ruleset) may spring up when this player's cities are taken. Happiness_To_Gold Make all Make_Content and Force_Content effects instead generate gold. Max_Trade_Routes - Number of trade routes that city can establish. - This is forced on trade route creation only. Existing trade routes - are never removed due to reduction of effect value. This is to - avoid micro-management, need to create same trade routes again - after their max number has been temporarily down. + Number of trade routes that city can establish. This is forced on trade route creation only. Existing +trade routes are never removed due to reduction of effect value. This is to avoid micro-management, need +to create same trade routes again after their max number has been temporarily down. Fanatics Units with "Fanatics" flag incur no upkeep. @@ -619,13 +555,12 @@ Not_Tech_Source Tech cannot be received from this player by any means. Trade_Revenue_Bonus - One time trade revenue bonus is multiplied by pow(2, amount/1000). - The amount value is taken from the caravan's home city. + One time trade revenue bonus is multiplied by pow(2, amount/1000). The amount value is taken from the + caravan's home city. Traderoute_Pct - Percentage bonus for trade from traderoutes. This bonus applies after - the value of the traderoute is already calculated. It affects one end - of the traderoute only. + Percentage bonus for trade from traderoutes. This bonus applies after the value of the traderoute is + already calculated. It affects one end of the traderoute only. Unhappy_Factor Multiply unhappy unit upkeep by amount. @@ -656,21 +591,17 @@ Output_Inc_Tile_Celebrate Tiles get amount extra output when city working them is celebrating. Upgrade_Price_Pct - Increases unit upgrade cost by amount percent. This effect works at - player level. You cannot adjust upgrade costs for certain unit type or - for units upgraded in certain city. + Increases unit upgrade cost by amount percent. This effect works at player level. You cannot adjust + upgrade costs for certain unit type or for units upgraded in certain city. Unit_Shield_Value_Pct - Increase the unit's value in shields by amount percent. When this effect - is used to determine how many shields the player gets for the actions - "Recycle Unit" and "Help Wonder" it gets access to unit state. When it is - used to influence the gold cost of "Upgrade Unit" it only has access to unit - type. + Increase the unit's value in shields by amount percent. When this effect is used to determine how many + shields the player gets for the actions "Recycle Unit" and "Help Wonder" it gets access to unit state. + When it is used to influence the gold cost of "Upgrade Unit" it only has access to unit type. Retire_Pct - The chance that unit gets retired (removed) when turn changes. - Retirement only happens if there are no enemy units or cities within - a few tiles. (This exists mainly to implement barbarian behavior.) + The chance that unit gets retired (removed) when turn changes. Retirement only happens if there are no + enemy units or cities within a few tiles. (This exists mainly to implement barbarian behavior.) Visible_Wall Instruct client to show specific buildings version of the city graphics. @@ -692,25 +623,23 @@ Unit_Buy_Cost_Pct Percentage added to unit buy cost. Shield2Gold_Factor - Factor in percent for the conversion of unit shield upkeep to gold upkeep. - A value of 200 would transfer 1 shield upkeep to 2 gold upkeep. The range - of this effect must be player or world. Note that only units with the - "Shield2Gold" flag will be affected by this. + Factor in percent for the conversion of unit shield upkeep to gold upkeep. A value of 200 would transfer + 1 shield upkeep to 2 gold upkeep. The range of this effect must be player or world. Note that only units + with the "Shield2Gold" flag will be affected by this. Tile_Workable If value > 0, city can work target tile. Migration_Pct - Increase the calculated migration score for the a city by amount in - percent. + Increase the calculated migration score for the a city by amount in percent. City_Radius_Sq - Increase the squared city radius by amount. Currently, this can only - usefully have "MinSize", "Building", or "Tech" requirements. + Increase the squared city radius by amount. Currently, this can only usefully have "MinSize", "Building", + or "Tech" requirements. City_Build_Slots - Increase the number of units with no population cost a city can build in - a turn if there are enough shields. + Increase the number of units with no population cost a city can build in a turn if there are enough + shields. City_Image The index for the city image of the given city style. @@ -725,13 +654,11 @@ History Value is how much history type (cumulative) culture city produces. National_Performance - Value is how much performance type culture, not tied to any specific city, - nation produces. + Value is how much performance type culture, not tied to any specific city, nation produces. National_History - Value is how much history type (cumulative) culture, not tied to any any - specific city, nation produces. + Value is how much history type (cumulative) culture, not tied to any any specific city, nation produces. Infra_Points - City increases owner's infra points by value each turn. If overall points - are negative after all cities have been processed, they are set to 0. + City increases owner's infra points by value each turn. If overall points are negative after all cities + have been processed, they are set to 0. diff --git a/docs/Modding/Rulesets/index.rst b/docs/Modding/Rulesets/index.rst new file mode 100644 index 0000000000..99cb29f40f --- /dev/null +++ b/docs/Modding/Rulesets/index.rst @@ -0,0 +1,21 @@ +Editing Rulesets +**************** + +Rulsets are a collection of plain text files that are formatted in a particular way in order to create the +rules of a Freeciv21 game. Rulesets are broken down into the following categories: + +* Buildings +* Cities +* Effects +* Game +* Governments +* Nations +* Styles +* Technology Tree +* Terrain +* Units + +.. toctree:: + effects.rst + :maxdepth: 1 + diff --git a/docs/Modding/index.rst b/docs/Modding/index.rst new file mode 100644 index 0000000000..0520c5ffd5 --- /dev/null +++ b/docs/Modding/index.rst @@ -0,0 +1,15 @@ +Modding +******* + +Modding + The Modding category is an area for documentation editors to provide tips and other details on modifying + aspects of Freeciv21 such as Rulesets, Musicsets, Soundsets and Tilesets. All of these areas allow for a + large amount of varyability in game play that is not hardcoded in the software. This is one of the + strengths of Freeciv21. + + +.. toctree:: + modpack-installer.rst + Rulesets/index.rst + :maxdepth: 1 + diff --git a/docs/Modding/modpack-installer.rst b/docs/Modding/modpack-installer.rst new file mode 100644 index 0000000000..165389a502 --- /dev/null +++ b/docs/Modding/modpack-installer.rst @@ -0,0 +1,239 @@ +Serving Modpacks for the Modpack Installer +****************************************** + +The rest of this document discusses how to set up a web server so that users can download modpacks you +publish. + +.. note:: If you just want to install modpacks, you need not read on. + +To host modpacks, you just need a web server that can host plain static files; you do not need to run any +custom code or frameworks on that web server, just to publish files with a specific layout, detailed below. + +On the modpack server, there are up to three layers of files required: + +1. A list of available modpacks (optional, advanced). +2. One control file per modpack. +3. The individual files comprising the modpacks. + +Each of these layers is described in detail below. + +Each layer refers to files in the next layer down. References can be with relative URLs (so that a modpack +or set of modpacks can be moved without changing any file contents), or with absolute URLs (so that the +different layers can be hosted on different web servers). + +Almost all of these file formats are specific to one major version of Freeciv21; this document only +describes the formats for the major version of Freeciv21 it is shipped with. + + +1. List of Modpacks +=================== + +This is only needed if you want to let users browse a list of available modpacks before choosing one to +install. To look at your modpack list instead of the standard one, users will usually have to start the +modpack installer with non-standard arguments (see above). + +The modpack list is a standard :literal:`JSON` file with a specific structure. + +Here's an example: + +.. code-block:: rst + + { + "info": { + "options": "+modpack-index-1.0", + "message": "Example modpack list loaded successfully" + }, + "modpacks": [ + { + "name": "Example", + "version": "0.0", + "license": "WTFPL", + "type": "Modpack", + "url": "https://example.com/example.json", + "notes": "This is an example" + } + ] + } + + +This file uses the modpack index format version 1.0, as is indicated in the :literal:`info.options` field. +The optional :literal:`info.message` is displayed on the status line when the modpack installer starts up. +It should be kept to one line. + +The modpacks list contains a list of modpacks. This example contains just one modpack. Each modpack may +contain the following fields: + +"name", "version", "type" + These three fields should match those in the :literal:`.json` file which :literal:`URL` links to. + +"subtype" + Optional free text. For tilesets or scenarios, conventionally indicates the map topology with one of + :literal:`overhead`, :literal:`iso`, :literal:`hex`, or :literal:`hex & iso` (and these will be + localised). Otherwise use :literal:`-`. + +"license" + Free text summarising the distribution terms for the modpack content, by naming a well-known license, not + quoting the full license text! Consider using SPDX identifiers (https://spdx.org/licenses/). + +"URL" + The URL to a :literal:`.json` file for the individual modpack. The URL can be either relative in which + case it's relative to the URL of :literal:`modpack.list`, or absolute - which can be on some other web + server. + +"notes" + Optional free text; usually shown as a tooltip. + + +2. Control File: Defining an Individual Modpack +=============================================== + +This is the core control file for a modpack, specifying what files it contains, where to download them from, +and where they are installed. + +Some modpack authors will just publish the URL of an :literal:`.json` file directly, for users to give to +the modpack installer tool. There doesn't have to be a :literal:`modpack.list` file anywhere that refers to +the :literal:`.json` file. + +Again, this is a file in standard :literal:`JSON` format. Its filename must end in :literal:`.json`. + +Here is an example of a modpack control file: + +.. code-block: rst + + { + "info": { + "options": "+modpack-1.0", + "base_url": ".", + "name": "Some ruleset", + "type": "Modpack", + "version": "0.0" + }, + "files": [ + "some_ruleset.serv", + "some_ruleset.tilespec", + "some_ruleset/nation/german.ruleset", + "some_ruleset/nation/indian.ruleset", + ... + ] + } + + +The :literal:`info` section has overall control information: + +"options" + Defines the version of the file format. Should be exactly as shown in the example. + +"name" + A short name for the modpack. This is used for version and dependency tracking, so should not + contain minor version information, and should not change once a modpack has been released for a given + major version of Freeciv21. Case-insensitive. + +"version" + Textual version information. If another modpack uses this one as a dependency, this string is + subject to version number comparison (using the rules of Freeciv21's :literal:`cvercmp` library, which + should give sensible results for most version numbering schemes). + +"type" + This must be one of the following: + +* :strong:`Ruleset`: :literal:`foo.serv`, :literal:`foo/*.ruleset`, :literal:`foo/*.lua`, etc. +* :strong:`Tileset`: :literal:`foo.tilespec`, :literal:`foo/*.png`, etc. +* :strong:`Soundset`: :literal:`foo.soundspec`, :literal:`foo/*.ogg`, etc. +* :strong:`Musicset`: :literal:`foo.musicspec`, :literal:`foo/*.ogg`, etc. +* :strong:`Scenario`: :literal:`foo.sav`; installed to a version-independent location. +* :strong:`Modpack`: Conventionally used for modpacks that contain more than one of the above kinds of material +* :strong:`Group`: Contains no files but only depends on other modpacks At the moment, only + :literal:`Scenario` causes special behavior. + +"base_url" + URL to prepend to the :literal:`src` filenames in the :literal:`files` list. May be relative to the + :literal:`.json` file -- starting with :literal:`./` -- or absolute in which case the files can be on some + web server different to where the :literal:`.json` file lives. + +The :strong:`files` list defines the individual files comprising your modpack. It must list every file +individually; any files in the same directory on the webserver that are not listed will not be downloaded. +Entries can be strings as shown above, in which case the same file name is used for downloading relative to +:literal:`info.base_url` and installing relative to the data directory. If the installed name is different +from the name on the server, the following syntax can be used instead: + +.. code-block: rst + + { + "url": "some-remote-file", + "dest": "where-to-install-it" + } + + +The URL can be either relative (to :literal:`info.base_url`) or absolute. The two syntaxes can be mixed in +the same modpack. + +.. note:: Forward slash :literal:`/` (and not backslash :literal:`\\`) should be used to separate directories. + +Some advice on the structure of files in modpacks: + +* You should generally install files in a directory named after the modpack, with a few exceptions + (:literal:`.serv`, :literal:`.tilespec`, :literal:`.soundspec`, and :literal:`.musicspec` files must be + installed to the top level, and should reference files in your subdirectory). Individual files and + directories install names should usually not embed version numbers, dates, etc., so that when a new version + of modpack X is installed, it cleanly overwrites the old version, rather than leaving both cluttering up + the user's installation. + +* The modpack installer does not stop different modpacks overwriting each other's files, so published + modpacks should be disciplined about namespace usage. If you've derived from someone else's modpack, you + should probably give your derivative new filenames, so that both can be installed simultaneously. + +* There is no :emphasis:`white-out` facility to delete files from a user's installation -- if a newer + version of a modpack has fewer files than an old one, the old file will persist in some users' + installations, so your modpacks should be designed to be tolerant of that. + +* At the moment, there is no restriction on what kind of files a given :emphasis:`type` can install, but + modpacks should stick to installing the advertised kinds of content. It's :strong:`OK` to install extra + files such as documentation in any case (:file:`LICENSE/COPYING`, :file:`README.txt`, etc.). + +* If your modpack contains a ruleset, you should usually install a :literal:`.serv` file at the top level + (which can be a one-line file consisting of :literal:`rulesetdir `, as this is needed for the server + to enumerate the available rulesets. + +In some cases, a modpack may depend on other modpacks, for instance if it reuses some of their files. This +can be handled by declaring a dependency with respect to the other modpack. Dependencies are listed in the +optional :literal:`dependencies` list of the :literal:`JSON` file. Each entry in that list must contain the +following object: + +.. code-block: rst + + { + "modpack": "...", + "url": "...", + "type": "...", + "version": "..." + } + + +The keys are explained below: + +* :strong:`modpack`: What the dependency modpack calls itself when installed (that is, :literal:`name` + from its :literal:`.json` file). +* :strong:`url`: URL to download modpack if needed. Can be relative or absolute. +* :strong:`type`: Must match :literal:`type` from dependency's :literal:`.json` file. +* :strong:`version`: Minimum version of dependency (as declared in its :literal:`.json` file). Subject to + version number comparison algorithm. + +If the modpack installer thinks the required version, or a newer version, of the dependency is already +installed, it will do nothing, otherwise it will download the dependency modpack, and any of its own +dependencies, recursively. + + +3. Individual Modpack Files +=========================== + +These are the files comprising the modpack (:literal:`*.ruleset`, :literal:`*.png`, etc.), that will be +copied verbatim to the user's Freeciv21 profile directory and read by the Freeciv21 client and server. The +modpack installer does not modify the files in any way. + +The files must be hosted individually on the web server; the modpack installer tool cannot unpack any +archives such as :file:`.zip` files. Individual scenarios can be compressed (e.g. :file:`.sav.gz`, as the +Freeciv21 engine can uncompress these files. + +Because the :literal:`*.json` file can change the file paths / names on download, the layout on the modpack server +doesn't have to correspond with the installed layout. An individual file can be shared between multiple +modpacks, if you want. diff --git a/docs/Playing/cma.rst b/docs/Playing/cma.rst new file mode 100644 index 0000000000..19e8ba4366 --- /dev/null +++ b/docs/Playing/cma.rst @@ -0,0 +1,208 @@ +Citizen Governor (aka Citizen Management Agent, or CMA) +******************************************************* + +The Citizen Governor is designed to help you manage your cities, i.e. deploy the workers on the available +tiles around (or make them scientists, taxmen, or even entertainers), to get the most out of the city. You +can switch the Governor on or off at any time for any city, but there are some handicaps (explained below), +if you have governor controlled and non-governor-controlled cities nearby. + +The heart of the Governor system is an optimizing algorithm, that tries to deploy the workers of a city in +such a way, that a user-defined goal is achieved as much as possible. You know probably, there is already a +kind of optimizing, when you open a city, and click on the center tile (the city symbol) of the mini map. +This optimization tries to maximize mostly the food output; but it doesn't care about disorder. + +The City Management Agent goes far beyond this old form of optimizing. First, it performs this task +every time anything changes with the city. If the city grows or shrinks, troops go in or out, tiles get +irrigation or mining, or are occupied by an enemy, the Governor 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. + +The legacy Freeciv Wiki also contains some other useful information related to the CMA: +* https://freeciv.fandom.com/wiki/City_manager +* https://freeciv.fandom.com/wiki/CMA + +Usage +===== + +You can set up the Governor for a city by opening the city window and clicking on the Governor tab. You can +choose a preset for a specified goal in the middle and on the bottom 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 a new +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. + +.. image:: ../_static/images/gui-elements/governor.png + :align: center + :height: 450 + :alt: Governor Tab in City Dialog + +The sliders are of two kinds: the rightmost sliders are factors, which gauges how 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 shields per round by setting the production surplus to 5. The most powerful constraint, +though, is the Celebrate constraint, which makes the city celebrate at once (which usually takes effect the +round after you change it). + +It is obvious that the Governor can't fulfill all these constraints in every case. Whenever the constraints +can't be fulfilled, the Governor quits its service for that city, giving a message: :strong:`"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, see below), 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 :guilabel:`Enable` to switch on the Governor. If +this button's text is greyed, either the Governor 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 +Governor deliberately, click :guilabel:`Disable`. + +Advanced Usage +============== + +Usually the goal(s) of your cities depend on the phase your game is in, whether you want to spread widely, +grow quickly, research advanced techs or wage war. You may want to set up a high factor for science to +research, or a high shields factor to produce units. The highest factor available is 25, that means: if the +shields factor is set to 25, and other to 1, the Governor prefers a single shield over 25 gold (or trade +also). This is pretty much because money can buy units too. That also means that the Governor is indifferent +about producing gold, science, luxury, and food; but when you wage war, you usually prefer gold or luxury. +So it's probably a good idea to set a second (or even third) preference for the city's output, e.g. gold +factor 5. That still prefers 1 shield over 5 gold (and 1 gold over 5 food or anything else). + +Constraints aren't useful in all cases. If you want a high income, it's probably better to set the gold +factor to 25, than to set a minimal surplus of 5 or so. Because a big city can make more gold than a small +one, you'd end up setting a different surplus for each city. + +However, if the shields surplus of a city is below zero, it cannot support all of its units any more. You +will lose some of the units the city supports. If the food surplus is negative, the city will starve and +eventually (when the granary is empty) shrink. This may be intended, but if the city supports any settlers, +you will lose them before the city shrinks. Constraints can also have a warning function. + +Which constraints can be fulfilled depends widely on the global science, tax, and luxury rates. E.g. a gold +surplus >= 0 is easier to fulfill with a higher tax rate than a lower one. You should always consider to +change these rates, when you going to change the Governor settings for the most of your cities. + +.. tip:: To avoid accidentally releasing your cities, when you change the rates, it is best to do so from + within the tax dialog rather than from the rates display in the main window. + +Drawbacks +========= + +The Governor is a very powerful tool, which not only releases you from the micromanagement of your cities, +but gives you more performance than you have ever seen (well, for most players). + +There are some drawbacks, though. Once you've switched on the Governor, it grabs any good tile it can get. +So you encounter very hard times trying to manage a city nearby a Governor-controlled one. This is true for +the city window and the main map worker's interface as well. If you want to have Governor-controlled and +:strong:`handmade` cities, they probably should be on different islands. + +There are several situations where the Governor can't fulfill the requirements just temporarily, e.g. when +you move a ship from one city to another, or when an enemy walks through your country. The Governor passes +back control in these cases, and you have to reenable it manually. A general approach to prevent this might +be, to set the minimal surpluses as low as possible (-20). Of course you must be careful with the food and +shield surpluses. + +While the Governor does a really good job for a single city, no tile will ever be released for the good of +another city. Also, the Governor controlled cities are computed in a more random order; the results may +depend on it and change, when a recalculation is done (when tax changes e.g.). So, no guarantee is given +that the overall results are always optimal. + +Settings file +============= + +The client allows the user to load and save preset parameters for the agent. Choosing :menuselection:`Game +--> Options --> Save Settings Now` will not only save your general options and message options, but it will +save any changes you made to you Governor presets as well. + +The format for the options file (usually :file:`~/.local/share/freeciv21/freeciv-client-rc-X.Y` , where X.Y +is the version of freeciv21 in use) is as follows (in case you which to change these presets manually, i.e. +with a text editor). + +Under the heading :literal:`[cma]`, is a :literal:`number_of_presets`. This should be set to the number of +presets that are present in the options file. If you manually add or remove a preset, you need to change +this number as appropriate. + +After this, is an array that houses the presets. Here is the header: + +.. code-block:: rst + + preset={ "name","minsurp0","factor0","minsurp1","factor1","minsurp2", + "factor2","minsurp3","factor3","minsurp4","factor4","minsurp5", + "factor5","reqhappy","factortarget","happyfactor" + +so the order of the preset should be as follows: + +* name of preset, minimal surplus 0, factor 0, ... , +* require city to be happy, what the target should be [0,1], +* the happiness factor + +Currently there are 6 surpluses and factors. They are: + +* 0 = food +* 1 = production +* 2 = trade +* 3 = gold +* 4 = luxury +* 5 = science + +Also currently, :literal:`factortarget` is not changeable within the client. + +The array should be terminated with a squirely brace :literal:`}`. + +Here are the 5 presets that come with Freeciv21 out of the box: + +.. code-block:: rst + + "Very happy",0,10,0,5,0,0,-20,4,0,0,0,4,FALSE,25 + "Prefer food",-20,25,0,5,0,0,-20,4,0,0,0,4,FALSE,0 + "Prefer production",0,10,-20,25,0,0,-20,4,0,0,0,4,FALSE,0 + "Prefer gold",0,10,0,5,0,0,-20,25,0,0,0,4,FALSE,0 + "Prefer science",0,10,0,5,0,0,-20,4,0,0,0,25,FALSE,01 + +Here are 16 more that you can add to your client RC file: + +.. code-block:: rst + + "+2 food",2,1,0,1,0,1,0,1,0,1,0,1,0,0,1 + "+2 production",0,1,2,1,0,1,0,1,0,1,0,1,0,0,1 + "+2 trade",0,1,0,1,2,1,0,1,0,1,0,1,0,0,1 + "+2 gold",0,1,0,1,0,1,2,1,0,1,0,1,0,0,1 + "+2 luxury",0,1,0,1,0,1,0,1,2,1,0,1,0,0,1 + "+2 science",0,1,0,1,0,1,0,1,0,1,2,1,0,0,1 + "+20 Celebrating for Gold",20,0,0,16,0,0,0,8,0,1,0,1,TRUE,0 + "Max food no gold limit",0,10,0,1,0,1,-20,1,0,1,0,1,0,0,1 + "Max production no gold limit",0,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 + "Max trade no gold limit",0,1,0,1,0,10,-20,1,0,1,0,1,0,0,1 + "Max gold no gold limit",0,1,0,1,0,1,-20,10,0,1,0,1,0,0,1 + "Max luxury no gold limit",0,1,0,1,0,1,-20,1,0,10,0,1,0,0,1 + "Max science no gold limit",0,1,0,1,0,1,-20,1,0,1,0,10,0,0,1 + "Max food+prod. no gold limit",0,10,0,10,0,1,-20,1,0,1,0,1,0,0,1 + "Max food+prod.+trade",0,10,0,10,0,10,0,1,0,1,0,1,0,0,1 + "Max all",0,1,0,1,0,1,0,1,0,1,0,1,0,0,1 + +Here are 6 more that have been added as an afterthought: + +.. code-block:: rst + + "+1 food, max prod. no gold limit",1,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 + "+2 food, max prod. no gold limit",2,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 + "+3 food, max prod. no gold limit",3,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 + "+4 food, max prod. no gold limit",4,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 + "+5 food, max prod. no gold limit",5,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 + "+6 food, max prod. no gold limit",6,1,0,10,0,1,-20,1,0,1,0,1,0,0,1 + +and even more, some with multiple goals: + +.. code-block:: rst + + "research at any cost",0,1,0,5,-20,1,-20,1,-20,1,-20,25,0,0,1 + "celebration and growing",1,1,0,25,-20,1,-20,12,-20,1,-20,1,1,0,1 + "grow at any cost",1,25,0,5,-20,1,-20,1,-20,1,-20,5,0,0,1 + "research and some shields",0,1,0,8,0,1,-3,1,0,1,0,25,0,0,1 + "shields and a bit money",0,1,0,25,0,1,-3,3,0,1,0,1,0,0,1 + "many shields and some money",0,1,0,25,0,1,0,9,0,1,0,1,0,0,1 + "shields and some research",0,1,0,25,0,1,-2,1,0,1,0,8,0,0,1 + "celebrate and grow at once",1,1,0,25,-20,1,-20,1,-20,1,-20,8,1,0,1 + +Enjoy using your citizen Governors! diff --git a/docs/Playing/how-to-play.rst b/docs/Playing/how-to-play.rst new file mode 100644 index 0000000000..3e735358ac --- /dev/null +++ b/docs/Playing/how-to-play.rst @@ -0,0 +1,220 @@ +How to Play Freeciv21 +********************* + +.. Custom Interpretive Text Roles for longturn.net/Freeciv21 +.. role:: unit +.. role:: improvement +.. role:: wonder + +If you're looking for how to install Freeciv21, look in :doc:`../General/install`. If you're looking for +how to get Freeciv21 running, look in the :doc:`../General/faq`. + +If you have never played the retail Civilization games, it's easiest to start by reading the legacy Freeciv +Manual, available separately at: http://www.freeciv.org/wiki/Manual + +If you're looking for ideas on playing Freeciv21, then keep reading!! + +Now that you have Freeciv21 running, you'll want to play your first few games. It is recommended that you +try playing solitaire a few times, so that you can get a feel for how things work, but this is not +necessary. You can also learn by playing with others or against the AI (aka Computer/CPU based player). + +Basic Strategy +============== + +First of all, this isn't a *perfect* strategy; it's not even a very good one. But it will get you started +playing Freeciv21. Part of the appeal of Freeciv21 is in developing new strategies. + +The game is divided into several stages: + +1. The Initial Expansion phase +2. Technological sub-phase +3. The Second Expansion phase +4. The Production phase +5. The Utter Annihilation of Your Enemies phase + +Initial Expansion +----------------- + +This phase is the most critical. The first thing you want to do is build cities and explore your island. You +want lots of cities, seven or eight at the least. + +The name of the game is to tie down as many squares of land as possible. When building a city, make sure +that you don't overlap too much with territory from one of your other cities. You can see which squares are +being used by a city by clicking on it. The map of the city and the surrounding area contains that city's +territory. Keeping this in mind, try to keep your cities fairly close together. The further apart they are, +the more difficult they are to defend and administer at this stage. + +.. tip:: Try to build on horses or near fish. + +Now that you have a city or two, you'll want to set the science rate as high as your government type will +allow. Don't worry about the tax rate, since you won't be building any improvements to drain your cash; +you'll be building settlers. Every city should be churning out settlers. The more settlers you make, the +more cities you can have; the more cities you have, the faster you gain tech; the faster you gain tech, the +faster you win. After you have built as many cities as your corner of the world will hold, turn the settlers +to irrigating and building roads. + +.. note:: If the food surplus in a city drops to +1 from supporting too many settlers, and you can't + rearrange people to increase it, then switch them to building temples. Unless you make contact with + another player, don't worry about building military units just yet. + +All this time, you have been gaining techs as fast as possible. What you should be shooting for is first +:strong:`The Republic`, then :strong:`Democracy`, then :strong:`Railroad`, and then +:strong:`Industrialization`. (Some people go for :strong:`Monarchy` before :strong:`The Republic`). As soon +as you've researched a new government type, start a revolution and change over to it. Cities operate much +better as Republics than they do under Despotism, but note that it's much harder to keep military units +outside of city limits under a Republic. Also, don't forget to recheck your rates after you've changed +governments, as the maximums vary for each type. + +When you get Democracy, you are equipped to go into the Second Expansion phase. This is accomplished by +changing the government to a Democracy, making all cities build temples, and setting the luxury rate to +100%. When you do this, all cities will immediately begin celebrating, and will grow at a rate of one per +turn as long as there is surplus food. When they've gotten big enough, set the luxury down to a reasonable +level of 20-40%. This places you in the Second Expansion phase. + +The down-side to this is that setting luxury to 100% means that your science research will all but stop. +After your cities have grown, and you put science back up to 50% or so, you will again gain techs, but at a +slightly slower rate. If you have done some exploring, and are not immediately threatened by another player, +it can be a good idea to keep science at maximum until techs start to take too long to generate. + +Second Expansion Phase +---------------------- + +When you get your cities to a good sized population, wean them off luxuries gradually and increase taxes. +Once they're down to 30% luxury or so, put as much of the taxes as you can into science, while maintaining +a positive income. When you get railroad, turn all your roads into rails, or at least the squares used +for production, or those that form part of a transport network. + +.. tip:: Turn every square used by a city into a road/rail, it increases that city's output. There's no need + to upgrade the very centre square - that's done automatically). + +Now is the time to develop industrialization, and military technologies. You should also begin building +cities on other islands, and do some serious exploring if you have not already done so. You need to find +out where your enemies are. Go for techs good for ships, and try to build :wonder:`Magellan's Expedition`. +When you feel ready, go into: + +Production Phase +---------------- + +Now you're building :improvement:`factories` and :improvement:`power plants` in your cities. You want to get +as much production as possible out of each city. Pollution becomes a problem. As soon as you can, try to +research Mass Production for :improvement:`Mass Transits`, and Recycling so you can build +:improvement:`Recycling Centers`. Once you've got all your cities going strong, you must build military +units. + +.. note:: If you come into contact with another player, you should immediately build a few attack units, and + at least one defense unit per city. + +When you want to begin thinking about attacking someone, set science to 0%, and put raise taxes as high as +you can without provoking disorder. Remember, money can build units too! + +Utter Annihilation of Your Enemies Phase +---------------------------------------- + +This can happen at any time, but it's more fun with the advanced weapons. + +Pick a relatively weak enemy, and send over a few ship-loads of troops. Take over his cities, and use them +to build more units to take out the rest of them with. Show no quarter! To the death! + +Repeat as often as necessary! + +.. note:: For pacifists: Freeciv21 also allows a player to win by building and launching a spaceship which + arrives at Alpha Centauri before anyone else. It is known as the Space Race victory. + + +Additional Questions that are Good for Getting Started +====================================================== + +:strong:`Q. What other strategies are there?` + +There are a number of tutorials and strategy guides available at the legacy Freeciv wiki - http://www.freeciv.org/wiki/Tutorials + +Plus, the Freeciv21 online help describes another strategy. + +:strong:`Q. In multiplayer games, what timeout should I set?` + +That depends upon the number of players. If there are just two of you playing, you can usually get away +with using timeout 0. If there are more than two, or if one of the two is going to be away from his +terminal at random intervals and you don't want to halt play, a timeout of 60 seconds is usually +sufficient. Later in the game, however, as things get more complex, you may want to extend the timeout to +240 seconds. In general, the more players you have, the longer a timeout you will need. Feel free to set +whatever timeout seems comfortable, but remember that going above 300 will tend to bother people. + +.. note: Longturn games have a timeout of 23 hours (82,800 seconds) + +:strong:`Q. What size map should I use?` + +The map size depends upon how many players there are, and how fast you want the game to end. The default +map size (80x50) is big enough for a fairly quick two player game, but will result in a *very* fast game if +any more than three people are participating. + +Fast games tend to be frustrating for everyone but the winner, as nobody has really had any time to develop +any defense. If you have more than three people playing, you should use an 80x80 map. If you have five or +more people, you probably want to consider one that's 100x100. + +:strong:`Q. What is that "generator" option?` + +It alters the map generation process. If you play Freeciv21 a few times without changing this setting, you +are sure to hear of (or experience) the horrors of a tiny island. Tiny Island Syndrome (TIS) is known to +make people go insane. To fix this, our kind and loving coders installed the generator option. + +* When set to :literal:`RANDOM`, it creates the map using a random height generator, with islands of different + (and potentially unfair) sizes. +* When set to :literal:`FRACTAL` it generates the map using a pseudo fractal height generator. This means + that the mountains and the hills will be placed according to everlasting mathematical figures. +* When set to :literal:`ISLAND` it generates islands of equal size (sometimes with some smaller islands + thrown in). This way, nobody can whine about losing :emphasis:`on account of that island`. +* When set to :literal:`SCENARIO` it is used for premade maps. Load a map by typing in :literal:`/load + /dir/savegame.sav.gz` in the input field at the bottom of the screen, in this way it is possible to change + the settings of a game. Use the map editor to change a map. +* :literal:`FAIR` is the most fair of all generators for the multiplayer games. It gives all users or teams + identical islands. +* :literal:`FRACTURE` generates maps from a fracture pattern. It tends to place hills and mountains along + the edges of the continents. + +Below the generator option there is the startpos option. This setting determines how many players are placed +on the same continent. Each generator option has its own default startpos value. Which is loaded when +startpos is :literal:`DEFAULT`. + +.. note:: The default startpos for the fractal height generator is ALL, which means that the + generator will try to place all the players on the same continent. + +:strong:`Q. Should I make the game easier by increasing the starting gold?` + +If you are inexperienced, and are playing with inexperienced people, probably no one will object to an +increase in the amount of gold they start with. This is, however, not a good way to learn how to play. +Starting out with lots of money makes the game much easier, and makes it more difficult for you to learn how +to cope with the default amount. Most experienced players don't increase this setting, and if they know how +to cope with it and you don't, you are going to go the way of Atlantis. + +.. note:: The same thing applies to the :literal:`techlevel` and :literal:`researchspeed` settings. + +:strong:`Q. What about those other settings?` + +The rest of them mainly have to do with what sort of world will be generated and game mechanics. Increasing +:strong:`specials` gives you a high chance of resources/square, and huts determines how many freebie huts there +are. Increasing the amount of settlers or explorers one starts with makes the game go faster, and allows +people to survive :emphasis:`those $#@! barbarians` which sometimes live in huts. + +The rail-related settings determine how much more a square will produce in food/trade/production with a +railroad on it, and the foodbox setting determines how much food each person in a city has to have before +a new person can be added. + +As for the rest, higher :strong:`mountains` means a more mountainous map, higher :strong:`deserts` means more +deserts, etc. + +:strong:`Q. How do I get _____ tech?` + +Look the tech up in the in-game help. It will show you the technologies you need to get first. + +You could read the technology ruleset in :file:`data/classic/techs.ruleset`. It shows a list of all the techs, +and what techs are necessary to get them. + +:strong:`Q. What kinds of military units are the most useful?` + +For Attack + :unit:`Armor` (tanks), :unit:`Helicopters`, :unit:`Cruise Missiles`, :unit:`Battleships`, :unit:`Transports`, :unit:`Nuclears`, :unit:`Howitzers`, and :unit:`Bombers`. + +For Defense + :unit:`Armor` (tanks), :unit:`Mech Infantry`, :unit:`Howitzers`, :unit:`Battleships`, :unit:`Cruise Missiles`, and :unit:`Nuclears`. + +Remember, the best defense is a strong offense. diff --git a/docs/Playing/index.rst b/docs/Playing/index.rst new file mode 100644 index 0000000000..8d62d91c2e --- /dev/null +++ b/docs/Playing/index.rst @@ -0,0 +1,13 @@ +Playing +======= + +Playing + The Playing category is an area for documentation editors to provide tips and tricks on ways to play + Freeciv21 and any of they varying rulesets that the longurn.net community likes to play. + + +.. toctree:: + how-to-play.rst + cma.rst + :maxdepth: 1 + diff --git a/docs/_static/images/211620_b_right_arrow_icon.png b/docs/_static/images/211620_b_right_arrow_icon.png new file mode 100644 index 0000000000..0b24f793f5 Binary files /dev/null and b/docs/_static/images/211620_b_right_arrow_icon.png differ diff --git a/docs/_static/images/gui-elements/governor.png b/docs/_static/images/gui-elements/governor.png new file mode 100644 index 0000000000..ebdc6d929a Binary files /dev/null and b/docs/_static/images/gui-elements/governor.png differ diff --git a/docs/_static/images/gui-elements/modpack-installer.png b/docs/_static/images/gui-elements/modpack-installer.png new file mode 100644 index 0000000000..000f4ee159 Binary files /dev/null and b/docs/_static/images/gui-elements/modpack-installer.png differ diff --git a/docs/_static/nsis-installer/01-Welcome.png b/docs/_static/images/windows-installer/01-Welcome.png similarity index 100% rename from docs/_static/nsis-installer/01-Welcome.png rename to docs/_static/images/windows-installer/01-Welcome.png diff --git a/docs/_static/nsis-installer/02-License.png b/docs/_static/images/windows-installer/02-License.png similarity index 100% rename from docs/_static/nsis-installer/02-License.png rename to docs/_static/images/windows-installer/02-License.png diff --git a/docs/_static/nsis-installer/03-Components.png b/docs/_static/images/windows-installer/03-Components.png similarity index 100% rename from docs/_static/nsis-installer/03-Components.png rename to docs/_static/images/windows-installer/03-Components.png diff --git a/docs/_static/nsis-installer/04-Admin-Multi-User.png b/docs/_static/images/windows-installer/04-Admin-Multi-User.png similarity index 100% rename from docs/_static/nsis-installer/04-Admin-Multi-User.png rename to docs/_static/images/windows-installer/04-Admin-Multi-User.png diff --git a/docs/_static/nsis-installer/05a-Admin-Folder.png b/docs/_static/images/windows-installer/05a-Admin-Folder.png similarity index 100% rename from docs/_static/nsis-installer/05a-Admin-Folder.png rename to docs/_static/images/windows-installer/05a-Admin-Folder.png diff --git a/docs/_static/nsis-installer/05b-User-Folder.png b/docs/_static/images/windows-installer/05b-User-Folder.png similarity index 100% rename from docs/_static/nsis-installer/05b-User-Folder.png rename to docs/_static/images/windows-installer/05b-User-Folder.png diff --git a/docs/_static/nsis-installer/06-Copy-Files.png b/docs/_static/images/windows-installer/06-Copy-Files.png similarity index 100% rename from docs/_static/nsis-installer/06-Copy-Files.png rename to docs/_static/images/windows-installer/06-Copy-Files.png diff --git a/docs/_static/nsis-installer/07-Finish.png b/docs/_static/images/windows-installer/07-Finish.png similarity index 100% rename from docs/_static/nsis-installer/07-Finish.png rename to docs/_static/images/windows-installer/07-Finish.png diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css index 84a929dab8..260a77c129 100644 --- a/docs/_static/theme_overrides.css +++ b/docs/_static/theme_overrides.css @@ -7,4 +7,52 @@ margin-bottom: 24px; max-width: 100%; overflow: visible; -} \ No newline at end of file +} + +/* format for custom interpretive text roles */ +.unit { + border:1px solid #7fbbe3; + background:#ffdf80; + font-size:80%; + font-weight:700; + border-radius:4px; + padding:2.4px 6px; + margin:auto 2px +} + +.unit::before { + content: "Unit: "; +} + +.improvement { + border:1px solid #7fbbe3; + background:#ffdf80; + font-size:80%; + font-weight:700; + border-radius:4px; + padding:2.4px 6px; + margin:auto 2px +} + +.improvement::before { + content: "City Improvement: "; +} + +.wonder { + border:1px solid #7fbbe3; + background:#ffdf80; + font-size:80%; + font-weight:700; + border-radius:4px; + padding:2.4px 6px; + margin:auto 2px +} + +.wonder::before { + content: "Wonder: "; +} + +/* add an underline for the title-reference interpretive text role */ +cite { + text-decoration: underline; +} diff --git a/docs/conf.py b/docs/conf.py index c87a3061fe..117c0c65cc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -87,7 +87,10 @@ # further. For a list of options available for each theme, see the # documentation. # -# html_theme_options = {} +html_theme_options = { + 'style_external_links': True + +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/index.rst b/docs/index.rst index 716992e845..9c6aa2294d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,14 +1,35 @@ -.. longturn-manuals documentation master file, created by - sphinx-quickstart on Tue Jun 22 20:24:24 2021. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. longturn-manuals documentation master file + +Welcome to longturn-manuals's Documentation! +******************************************** + +Welcome to the longturn.net community Freeciv21 Documentation Project. The documentation is broken into +four categories: + +General + The General category is a catch-all for content that does not neatly fit into the other three. Things like + the FAQ and installation instructions go here. + +Playing + The Playing category is an area for documentation editors to provide tips and tricks on ways to play + Freeciv21 and any of they varying rulesets that the longurn.net community likes to play. + +Modding + The Modding category is an area for documentation editors to provide tips and other details on modifying + aspects of Freeciv21 such as Rulesets, Musicsets, Soundsets and Tilesets. All of these areas allow for a + large amount of varyability in game play that is not hardcoded in the software. This is one of the + strengths of Freeciv21. + +Developing + The Developing category is an area for documentation editors to provide information on how to alter the + source code of Freeciv21 and contribute to the project in general. -Welcome to longturn-manuals's documentation! -============================================ .. toctree:: - install/index.rst - rulesets/index.rst + General/index.rst + Playing/index.rst + Modding/index.rst + Developing/index.rst :maxdepth: 2 :caption: Contents: @@ -19,3 +40,8 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` + +.. Custom Interpretive Text Roles for longturn.net/Freeciv21 +.. role:: unit +.. role:: improvement +.. role:: wonder diff --git a/docs/install/index.rst b/docs/install/index.rst deleted file mode 100644 index 432ce7b540..0000000000 --- a/docs/install/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -Installation -============ - -.. toctree:: - install.rst - windows-install.rst - diff --git a/docs/rulesets/index.rst b/docs/rulesets/index.rst deleted file mode 100644 index 5f280320bf..0000000000 --- a/docs/rulesets/index.rst +++ /dev/null @@ -1,6 +0,0 @@ -Editing rulesets -================ - -.. toctree:: - effects.rst -