Since version 2.3 freeciv contains a modpack installer (freeciv-modpack) for downloading and installing custom content. Users only need to enter a modpack URL, and it will be automatically correctly installed. Users are not more forced to download and copy each file to the correct directory manually, where correct was something that nobody seemed to know what it is for some operating systems. This document describes how you as custom modpack author can make your content available for an installation with freeciv-modpack.
Hosting place
First of all you need some place in the Internet to store your modpack where freeciv-modpack can fetch it from. Current versions of freeciv-modpack support downloading only by http, so you need content on a web-server, e.g., your homepage, but not an ftp-server. Currently freeciv-modpack has no way to unpack any archives, and each file of your modpack must be separately downloadable. Individual sceanarios can be of course compressed (gzip or xz, bzip2 will be removed.)
.modpack-file
In addition to all the normal contents of your modpack you have to create one file that instructs freeciv-modpack in the download process. This file must have a .modpack-suffix and it determines the modpack URL specified by the user in freeciv-modpack. It is a text file similar to other data file formats freeciv uses, so you as modpack author are already quite familiar with the INI-like syntax of this format.
[info]
options = "+modpack-090810-2"
baseURL = "http://www.cazfi.net/freeciv/modinst/2.3/ancients"
name = "Example" Since 2.4
type = "Ruleset" Since 2.4
version = "1.0-beta2" Since 2.4
[files]
list =
{
"src", "dest"
"ancients.serv"
"ancients.tilespec"
"ancients/nation/german.ruleset"
...
"ancients/README"
}
info.options gives a capability string of this modpack-file. For content to be downloaded with the freeciv 2.3 freeciv-modpack this must be "+modpack-090810-2", and for 2.4 it must be "+modpack-150611".
info.baseURL gives a common beginning of the URLs files can be downloaded from, so you don't need to give full URL for every file in your modpack. In the above example all the files of the ancients.modpack are placed under the directory http://www.cazfi.net/freeciv/modinst/2.3/ancients.
info.name is the name of the modpack.
info.type is the type of this custom content package; one of "Ruleset", "Tileset", "Modpack", or "Scenario". This affects where content gets installed. Scenarios (consisting only of one optionally compressed .sav faile) are freeciv version independent and stored in a location shared by all freeciv versions, typically ~/.freeciv/scenarios. All other types belong to a specific freeciv version (a "branch" in SVN terminology, e.g., 2.5), and are installed under a version specific directory, e.g., ~/.freeciv/2.5/name.
info.version is a version string for your modpack.
files.list is the list of files to download. For each file at least src must be given. It is the end of the URL for this particular file. The first file to download in the example above is http://www.cazfi.net/freeciv/modinst/2.3/ancients/ancients.serv. dest is what the file should be called when installed, relative to the main installation directory. If dest is omitted, src is used for this too.
Modpack UI icon
modpack.list
- Background, not really relevant for modpack authors, just for the records.
The modpack.list is a list maintained by the freeciv team about high profile .modpack files. The URL for that list is hardcoded to freeciv-modpack, and for freeciv 2.3 it was http://download.gna.org/freeciv/modinst/2.3/modpack.list. To install a modpack from that list users do not need to know any URLs at all. Since 2.4 it is possible to override the URL with a commandline parameter "-L <URL>". This is mainly meant for testing freeciv-modpack during development.
[info]
options = "+Freeciv-2.3-modlist"
message = "Freeciv 2.3 is expected to be released quite soon now."
[modpacks]
list =
{
"name", "version", "type", "license", "URL"
"Amplio", "S2_3", "Tileset", "GLP2+", "http://www.cazfi.net/freeciv/modinst/2.3/amplio.modpack"
"Ancients", "2.3-0", "Ruleset", "GPL2+", "http://www.cazfi.net/freeciv/modinst/2.3/ancients.modpack"
}
info.options is the capability string of this modpack.list file. For a list compatible with freeciv 2.3 freeciv-modpack it must be "+Freeciv-2.3-modlist", and for freeciv 2.4 it must be "+modlist-011111".
info.message is an optional message to be shown over a freeciv-modpack connection.
modpacks.list is a list of .modpack-files. The name and version are currently just texts to be shown to the user. The type is one of Ruleset, Tileset, Modpack, or, starting from 2.4, Scenario. The license is a new field in 2.4 containing the name of the modpack's license. URL is where the .modpack file can be downloaded.
modpack.db
- Modpack installation procedures used for 2.5 and partially 2.4:
As of version 2.5 the modpack installer saves information about locally installed modpacks to a modpack.db file. The .db file extension is arguably a bad idea for Windows, maybe 2.6 or later pick something less ambiguous, e.g., ~/.freeciv/3.0/.control/modpack.spec could be good enough (GNA#24673).
The ~/.freeciv/2.5/.control/modpack.db is created by the relevant modpack installer based on what you have installed from modpack.freeciv.org/2.5 (default) or similar servers. Based on modpack.list files on the default server for 2.4, 2.5, 2.6, and later the modpack installer can also determine which modpacks are not yet installed or not the latest version.
UIs
For Freeciv 2.5 the former freeciv-modpack.exe (on Windows) was renamed to freeciv-mp-UI.exe for UI gtk2, gtk3, sdl, qt, and more. For Freeciv 2.6 and later there will be also a command line modpack installer. TBD: It's not obvious what "Portable APPs" (PAF) distributions will use as ~/.freeciv home directory; please add some details here or link to a new PAF page on this wiki with more "Portable APPs" observations.