If you want to contribute a new add-on, information how to create add-ons can be found here.
New add-ons, or upgrades for existing ones, as well as new or updated screenshots, can be uploaded to the server from the in-game add-ons manager (Widelands 1.1 or newer). It is also possible to submit add-ons and screenshots on the forum: https://www.widelands.org/forum/topic/5073
Before running the server, be sure a Java Development Kit (JDK) is installed to compile the Java programs.
Before starting the server, ensure that a MySQL server is running somewhere, and that an ini-style config file called config exists in the working directory. The setup is detailed below.
Starting the add-ons webserver is as simple as typing ./server.sh. This will launch the webserver on the specified port of your machine. In order to connect to this server from the game, run Widelands with the commandline parameters --addon_server_ip=127.0.0.1 --addon_server_port=7388 (where you replace 127.0.0.1 with the IP of the machine on which you’re running the server and 7388 with the port number from the config file).
Note that the server runs as a daemon; that is, it is independent from your process and all output is redirected to a file called server.log which will be overwritten on every run. To terminate the server daemon, retrieve the PID of the process from the second line of the logfile and then type kill <PID>.
The server protocol is documented in wl/server/Command.java.
Widelands version 1.0 and older does not connect to the server. It instead downloads and parses the list* files in this repository and then downloads each file belonging to an add-on separately. Every change to an add-on must therefore be reflected in the list* files so that the full add-on selection is available also to Widelands 1.0 users.
For this reason, the server automatically syncs its repo checkout with the GitHub repo every night. Normally, all required steps are done fully automatically. Occasionally, a merge conflict may arise which may prove too difficult for the server to handle on its own.
Whenever an error that requires a maintainer’s attention occurs on the add-ons server, an e-mail notification will automatically be posted to all subscribed maintainers.
config File| Key | Description | Example |
|---|---|---|
port |
Port number for the server | 7388 |
name |
Human-readable name to show to the user. | Alpha |
githubusername |
User name for GitHub | bunnybot |
githubtoken |
Personal Access Token for GitHub | 123456abcdef |
transifextoken |
Bearer token for Transifex | 1/abcdef123456 |
muninpassword |
Arbitrary password for munin integration scripts | 123456 |
databasehost |
IP address of the MySQL server | 127.0.0.1 |
databaseport |
Port number of the MySQL server | 3306 |
website_database |
Name of the website database | wl_addons_server_website |
website_db_user |
The database user of the websitedatabase | websiteuser |
website_db_password |
Password for the website database user | 123456 |
addons_database |
Name of the add-ons database | wl_addons_server_addons |
addons_db_user |
The database user of the addons database | addonuser |
addons_db_password |
Password of the addons database user | 123456 |
noticetype_new |
Name of the notice type for new add-ons in the website database | new |
noticetype_deleted |
Name of the notice type for add-on deletion in the website database | deleted |
noticetype_transifex-issues |
Name of the notice type for Transifex string issues in the website database | transifex-issues |
noticetype_comment-added |
Name of the notice type for new comments in the website database | comment-added |
noticetype_comment-mention |
Name of the notice type for @mentions in comments in the website database | comment-mention |
website_maps_path |
Base path where website maps are stored | /var/wlmedia |
website_maps_slug |
Slug for the content type of comments on website maps | wlmaps |
deploy |
Whether this server is the real thing, not just a test environment | true or false |
The MySQL server needs to have two databases called the website database and the add-ons database. You can also use just one database which meets the specifications of both, but it is recommended to keep them separate. There needs to be a MySQL user with SELECT access to the website database and (SELECT, INSERT, DELETE) access to the add-ons database.
| Table | Column Names | Column Types | Comment |
|---|---|---|---|
auth_user |
id username email |
int varchar varchar |
|
wlggz_ggzauth |
user_id password permissions |
int varchar int |
- - 7 means normal user,127 means admin |
wladdons_settings_addonnoticetype |
id slug send_default author_related_default |
int varchar tinyint tinyint |
|
wladdons_settings_addonnoticeuser |
user_id notice_type_id shouldsend |
int int tinyint |
| Table | Column Names | Column Types | Comment |
|---|---|---|---|
txissues |
id |
varchar |
|
addons |
id name timestamp edit_timestamp i18n_version security quality downloads |
int varchar bigint bigint int tinyint int int |
Unique add-on ID - - - - 0 means unchecked, 1 means verified 0 means unchecked, 1/2/3 means Poor/Good/Excellent - |
uploaders |
addon user |
int int |
An add-on can have multiple uploaders. Each uploader goes on a separate row. |
uservotes |
addon user vote |
int int int |
|
usercomments |
id addon user timestamp editor edit_timestamp version message |
int int int bigint int bigint varchar varchar |
Unique comment ID - - - May be NULL May be NULL - - |
notifyadmins |
email level |
varchar int |
-0 means disabled, 1 critical only, 2 all notices |
upload_override |
id name filesize nrfiles nrdirs upload_interval |
int varchar bigint bigint bigint bigint |
Add-ons are keyed by name. All entries may be NULL to use the defaults. |
To verify a new add-on (or an existing one after an update), read the code carefully and make sure it does not contain malicious code. Also check for potentially desync-prone code pieces. Then, in the Widelands add-on manager, select the add-on in the Browse tab, go to the Comments & Votes window, and use the admin interface to set the add-on’s security, sync-safety, and quality properties as appropriate.
If the add-on was not up for translation on Transifex yet, additionally enable Transifex integration for the add-on via the admin interface. You will need to set the Display Name (which should match the add-on’s name) and the Priority of the new resource. Add-ons officially provided by the Widelands Development Team get highest priority. Add-ons which have not been verified yet should not appear on Transifex in the first place, but if they do, they get the lowest priority. All other add-ons get medium priority. Also add appropriate category tags to the resources: Every resource gets the add-on’s category as a tag. The few official add-ons also get the "Official" tag and perhaps other tags as appropriate (e.g. "Tournament" for add-ons used in an official tournament).
Anyone who wants to be dropped a notification about important events such as server sync errors or add-on submissions should add themselves to the notifyadmins table. Use subscription level 1 to subscribe only to critical events, or any higher number to subscribe to all messages; 0 disables notifications.
insert into notifyadmins (email, level) value ('my.address@example.com', 2);Translating should be done on Transifex: https://www.transifex.com/widelands/widelands-addons/
Do not modify any of the files in po/ manually – your changes will be discarded during the automated translation updates.
The server periodically syncs the translations with Transifex and compiles them for download.
If you encounter any issues related to a specific add-on, please do not report them against the official game! Report them on this repository instead.
Issues related to the add-on system in general, or not related to add-ons at all, should be reported against the official game.
Keep in mind that some of the add-ons here (only the ‘Dummy Campaign’ currently) are meant as proof-of-concept dummies. Please do not report any errors regarding those.
This repository and its contents are published under the same license as Widelands: The GNU General Public License (GPL) v2.
The file mysql-connector-java-8.0.23.jar is third-party code which we use with great gratitude to the authors. It contains its own LICENSE file.
The file json-simple-1.1.1.jar is third-party code which we use with great gratitude to the authors. It is licensed under the Apache License 2.0.