Merge lp:~widelands-dev/widelands/document_world into lp:widelands

[GunChleoc]

Started adding documentation for world entities.

More documentation. Immovable and critter programs as well as map generation are still missing here and will have to be done in a follow-up branch.

[bunnybot (widelandsofficial)]

Continuous integration builds have changed state:

Travis build 2624. State: passed. Details: https://travis-ci.org/widelands/widelands/builds/270101584.
Appveyor build 2446. State: success. Details: https://ci.appveyor.com/project/widelands-dev/widelands/build/_widelands_dev_widelands_document_world-2446.

[kaputtnik (franku)]

Some proofreading. The part in new_editor_<element_type>_category{table} is quite complicated for me.

Did not read all.

[kaputtnik (franku)]

Proof reading done and added some more diff comments.

Especially in terrains the 'is' value and the 'valid_resource' value depend on each other. Don't know how to explain that though. https://bugs.launchpad.net/widelands/+bug/1505345/comments/1

[GunChleoc (gunchleoc)]

Thanks for your comments. For the is value, I have linked to the bug now - I think explaining that in detail is out of scope for the documentation, since it's a bug.

I have fiddled a bit with the editor category documentation, but I am not thrilled by the results either. I'd like to revisit that later in https://code.launchpad.net/~widelands-dev/widelands/dynamic_world_loading, since I'll be changing the API there. I think the new API will also be easier to explain. The "element" thing is a bit tricky ere - I can't just say "Map Object", because terrains are not map objects.

[kaputtnik (franku)]

Thanks :-)

For the Animals it should be clarified, that 'fish' is a resource, and does not belong to the critters, imho.

Regarding the editor category documentation:
From my understanding there are only three types available (at the moment) and adding a new element_type is not possible. So why not document similar to the workers? E.g.:

"This file also defines the editor categories for world elements like terrains or immovables so that they will be added to their respective editor tools (Place terrain, Place immovable etc.). The available categories are:

- new_editor_terrain_category{table}
- new_editor_immovable_category{table}
- new_editor_critter_category{table}

All categories have the same properties in the argument table:

(listing the table entries)
"

So we get rid of the abstract term "new_editor_<element_type>_category{table}".

[GunChleoc (gunchleoc)]

Thanks, that looks much better now :)

I also ripped out the duplicate documentation in lua_root and linked to the new documentation there.

[kaputtnik (franku)]

Could not resist to make a suggestion. Feel free to revert it.

[GunChleoc (gunchleoc)]

LGTM, thanks :)

@bunnybot merge

=== modified file 'data/world/critters/badger/init.lua'
--- data/world/critters/badger/init.lua	2017-02-12 09:10:57 +0000
+++ data/world/critters/badger/init.lua	2017-09-03 10:57:20 +0000
@@ -1,3 +1,14 @@
+-- RST
+-- .. _lua_world_critters:
+--
+-- Critters (Animals)
+-- ------------------
+--
+-- Critters are entities owned by the world that will move around the map at random, usually animals. On how to add fish to the map, see :ref:`lua_world_resources`.
+--
+-- Critters are defined in
+-- ``data/world/critters/<critter_name>/init.lua``.
+
 dirname = path.dirname(__file__)
 
 animations = {
@@ -10,6 +21,44 @@
 
 add_walking_animations(animations, "walk", dirname, "walk", {13, 15}, 20)
 
+-- RST
+-- .. function:: new_critter_type{table}
+--
+--    This function adds the definition of a critter to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will add to this critter. It contains the following entries:
+--
+--    **name**
+--        *Mandatory*. A string containing the internal name of this critter, e.g.::
+--
+--            name = "badger",
+--
+--    **descname**
+--        *Mandatory*. The translatable display name, e.g.::
+--
+--            descname = _"Badger",
+--
+--    **editor_category**
+--        *Mandatory*. The category that is used in the editor tools for placing a critter of this type on the map, e.g.::
+--
+--            editor_category = "critters_carnivores",
+--
+--    **attributes**
+--        *Mandatory*. Attributes can be used by other programs to identify a class of critters, e.g.::
+--
+--            attributes = { "eatable" }, -- This animal can be hunted
+--
+--    **programs**
+--        *Mandatory*. Every critter has an automatic default program, which is to move around the map at random. Additional programs can be defined that other map objects can then call in their programs, e.g.::
+--
+--            programs = {
+--               remove = { "remove" }, -- A hunter will call this after catching this animal
+--            },
+--
+--    **animations**
+--        *Mandatory*. A table containing all animations for this critter. Every critter
+--        needs to have an ``idle`` and a directional ``walk`` animation.
+--        See :doc:`animations` for a detailed description of the animation format.
 world:new_critter_type{
    name = "badger",
    descname = _ "Badger",

=== modified file 'data/world/immovables/bush1/init.lua'
--- data/world/immovables/bush1/init.lua	2015-11-03 18:18:27 +0000
+++ data/world/immovables/bush1/init.lua	2017-09-03 10:57:20 +0000
@@ -1,5 +1,103 @@
+-- RST
+-- .. _lua_world_immovables:
+--
+-- Immovables
+-- ----------
+--
+-- Immovables are entities owned by the world that are placed in a fixed position
+-- on the map. They include trees, rocks, artifacts, and eye candy.
+--
+-- Immovables are defined in
+-- ``data/world/immovables/<immovable_name>/init.lua``.
+-- Some immovables are grouped into subdirectories, e.g. trees and rocks.
+-- There are also some specialized immovables:
+--
+-- * `Artifacts`_
+-- * `Rocks`_
+-- * `Trees`_
+
 dirname = path.dirname(__file__)
 
+-- RST
+-- .. function:: new_immovable_type{table}
+--
+--    This function adds the definition of an immovable to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will add
+--       to this immovable. It contains the following entries:
+--
+--    **name**
+--        *Mandatory*. A string containing the internal name of this immovable, e.g.::
+--
+--            name = "alder_summer_old",
+--
+--    **descname**
+--        *Mandatory*. The translatable display name, e.g.::
+--
+--            descname = _"Alder (Old)",
+--
+--    **species**
+--        *Mandatory for trees*. `Trees`_ have 4 variants (sapling, pole, mature, and old),
+--        so we will want a simplified translatable display name for the editor help, e.g.::
+--
+--            species = _"Alder",
+--
+--    **editor_category**
+--        *Mandatory*. The category that is used in the editor tools for placing an
+--        immovable of this type on the map, e.g.::
+--
+--            editor_category = "trees_deciduous",
+--
+--    **size**
+--        *Optional*. The size of the immovable. Defaults to ``none`` -
+--        note that immovables with size ``none`` will be removed when
+--        their space is needed for a road. Possible values
+--        are ``none``, ``small``, ``medium``, and ``big``, e.g.::
+--
+--            size = "small",
+--
+--    **attributes**
+--        *Optional*. Attributes can be used by other programs to identify a class
+--        of immovables, e.g.::
+--
+--            attributes = { "tree" }, -- This is a tree, so it can be felled
+--
+--    **programs**
+--        *Mandatory*. Every immovable has an automatic default program,
+--        which will simply play the ``idle`` animation. Leave the table empty if
+--        this is all you need. You can also overwrite this default ``program``,
+--        like this::
+--
+--            program = {
+--               "animate=idle 50000",
+--               "remove=18",
+--               "grow=alder_summer_old",
+--            },
+--
+--    **terrain_affinity**
+--        *Mandatory for trees*. If your immovable is a tree (c.f. `Trees`_), you will need to specify its
+--        terrain affinity, which will determine its chances to survive on different
+--        terrains. Terrain affinity is a table and looks like this::
+--
+--          terrain_affinity = {
+--             -- Temperature is in arbitrary units.
+--             preferred_temperature = 125,
+--
+--             -- In percent (1 being very wet).
+--             preferred_humidity = 0.65,
+--
+--             -- In percent (1 being very fertile).
+--             preferred_fertility = 0.6,
+--
+--             -- A value in [0, 1] that defines how well this immovable can deal with non-ideal terrain.
+--             -- A lower value means that it is less picky, i.e. it can deal better with it.
+--             pickiness = 0.6,
+--          }
+--
+--    **animations**
+--        *Mandatory*. A table containing all animations for this immovable.
+--        Every immovable needs to have at least an ``idle`` animation.
+--        See :doc:`animations` for a detailed description of the animation format.
 world:new_immovable_type{
    name = "bush1",
    descname = _ "Bush",
@@ -14,3 +112,46 @@
       },
    }
 }
+
+-- RST
+--
+-- Artifacts
+-- ^^^^^^^^^
+-- Artifacts are immovables that players can hunt for when using the "Artifacts" win condition.
+-- They need to define the ``artifact`` attribute in order for the win condition to find them,
+-- and should be placed in the editor_category "artifacts".
+--
+-- Rocks
+-- ^^^^^
+-- Rocks are a special type of immovable that can be quarried by a stonecutter.
+-- They need to define the ``rocks`` attribute in order for the stonecutter to find them,
+-- and should be placed in the editor_category "rocks".
+-- Rocks will shrink over time and disappear eventually while being quarried.
+-- This shrinking is implemented via their ``shrink`` program, which will be triggered
+-- by the stonecutter. Rocks usually come in series of 6 immovables:
+--
+-- * **<rock_name>6 - <rock_name>2**: These rocks will transform into the next smaller rock by calling ``transform``
+--   in their ``shrink`` program.
+--
+-- * **<rock_name>1**: This is the smallest rock, so it needs to call ``remove`` in its ``shrink``
+--   program in order to disappear from the map.
+--
+-- Trees
+-- ^^^^^
+--
+-- Trees are a special type of immovable, and should be placed in the editor_category
+-- "trees_coniferous", "trees_deciduous", "trees_palm", or "trees_wasteland".
+-- Because they will grow with time, this growth is represented by transforming one
+-- tree into the next through the ``grow`` command in their program.
+-- They also all need to define a species name and their terrain affinity (see above).
+-- Trees will grow in 4 stages:
+--
+-- * **Sapling**: A sapling will be seeded by another tree or planted by a forester.
+--   All saplings have the attribute ``"tree_sapling"``.
+-- * **Pole**: A young, slender tree that is not able to seed other trees yet.
+--   A pole has no special attributes.
+-- * **Mature**: A visually grown tree but without any special attributes, just like the pole.
+-- * **Old**: Old trees can be felled, which is defined by the attribute ``tree``.
+--   They will also die off and seed a new tree via the ``transform`` and ``seed``
+--   commands in their program. They also need to specify a ``fall`` program,
+--   which will be triggered when a lumberjack fells them.

=== modified file 'data/world/init.lua'
--- data/world/init.lua	2017-02-12 09:10:57 +0000
+++ data/world/init.lua	2017-09-03 10:57:20 +0000
@@ -1,3 +1,15 @@
+-- RST
+-- init.lua
+-- --------
+--
+-- World initialization.
+-- All world entities are loaded via this file.
+--
+-- This file also defines the editor categories for world elements like terrains or
+-- immovables so that they will be added to their respective editor tools (Place Terrain,
+-- Place Immovable etc.). There are three categories available,
+-- each with their own function:
+
 world = wl.World()
 
 set_textdomain("world")
@@ -11,126 +23,61 @@
    end)
 
    print_loading_message("┃    Terrains", function()
+
+-- RST
+-- .. function:: new_editor_terrain_category{table}
+--
+--    This function adds the definition for a category in the "Terrains" tool.
+--    Only terrains can be in this editor category. The parameter `table` is described below.
+
+      world:new_editor_terrain_category{
+         name = "summer",
+         descname = _ "Summer",
+         picture = "world/pics/editor_terrain_category_green.png",
+         items_per_row = 6,
+      }
+      world:new_editor_terrain_category{
+         name = "wasteland",
+         descname = _ "Wasteland",
+         picture = "world/pics/editor_terrain_category_wasteland.png",
+         items_per_row = 6,
+      }
+      world:new_editor_terrain_category{
+         name = "winter",
+         descname = _ "Winter",
+         picture = "world/pics/editor_terrain_category_winter.png",
+         items_per_row = 6,
+      }
+      world:new_editor_terrain_category{
+         name = "desert",
+         descname = _ "Desert",
+         picture = "world/pics/editor_terrain_category_desert.png",
+         items_per_row = 6,
+      }
+
       include "world/terrains/init.lua"
    end)
 
-   world:new_editor_immovable_category{
-      name = "miscellaneous",
-      descname = _ "Miscellaneous",
-      picture = "world/immovables/ruin5/idle.png",
-      items_per_row = 6,
-   }
-
-   world:new_editor_immovable_category{
-      name = "artifacts",
-      descname = _ "Artifacts" .. "<br>" .. _ "These immovables are used by the win condition “Artifacts”.",
-      picture = "world/immovables/manmade/artifacts/artifact00/idle.png",
-      items_per_row = 6,
-   }
-
-   world:new_editor_immovable_category{
-      name = "plants",
-      descname = _ "Plants",
-      picture = "world/immovables/cactus3/idle.png",
-      items_per_row = 8,
-   }
-
-   world:new_editor_immovable_category{
-      name = "standing_stones",
-      descname = _ "Standing Stones",
-      picture = "world/immovables/standing_stones/standing_stone4_desert/idle.png",
-      items_per_row = 4,
-   }
-
-   world:new_editor_immovable_category{
-      name = "rocks",
-      descname = _ "Rocks",
-      picture = "world/immovables/rocks/greenland_rocks6/idle.png",
-      items_per_row = 6,
-   }
-
-   world:new_editor_immovable_category{
-      name = "trees_dead",
-      descname = _ "Dead Trees",
-      picture = "world/immovables/trees/deadtree2/idle.png",
-      items_per_row = 8,
-   }
-
-   world:new_editor_immovable_category{
-      name = "trees_coniferous",
-      descname = _ "Coniferous Trees",
-      picture = "world/immovables/trees/spruce/old/idle_0.png",
-      items_per_row = 8,
-   }
-
-   world:new_editor_immovable_category{
-      name = "trees_deciduous",
-      descname = _ "Deciduous Trees",
-      picture = "world/immovables/trees/alder/old/idle_0.png",
-      items_per_row = 8,
-   }
-
-   world:new_editor_immovable_category{
-      name = "trees_palm",
-      descname = _ "Palm Trees",
-      picture = "world/immovables/trees/palm_borassus/old/idle_0.png",
-      items_per_row = 8,
-   }
-
-   world:new_editor_immovable_category{
-      name = "trees_wasteland",
-      descname = _ "Wasteland Trees",
-      picture = "world/immovables/trees/umbrella_red/old/idle_0.png",
-      items_per_row = 8,
-   }
-
-   world:new_editor_critter_category {
-      name = "critters_herbivores",
-      -- TRANSLATORS: A category in the editor for placing animals on the map.
-      descname = _ "Herbivores",
-      picture = "world/critters/sheep/idle_00.png",
-      items_per_row = 10,
-   }
-
-   world:new_editor_critter_category {
-      name = "critters_carnivores",
-      -- TRANSLATORS: A category in the editor for placing animals on the map.
-      descname = _ "Carnivores",
-      picture = "world/critters/fox/idle_00.png",
-      items_per_row = 10,
-   }
-
-   world:new_editor_critter_category {
-      name = "critters_aquatic",
-      -- TRANSLATORS: A category in the editor for placing animals on the map.
-      descname = _ "Aquatic",
-      picture = "world/critters/duck/idle_00.png",
-      items_per_row = 10,
-   }
-
    print_loading_message("┃    Immovables", function()
-      include "world/immovables/grass1/init.lua"
-      include "world/immovables/grass2/init.lua"
-      include "world/immovables/grass3/init.lua"
-      include "world/immovables/bush1/init.lua"
-      include "world/immovables/bush2/init.lua"
-      include "world/immovables/bush3/init.lua"
-      include "world/immovables/bush4/init.lua"
-      include "world/immovables/bush5/init.lua"
-      include "world/immovables/cactus1/init.lua"
-      include "world/immovables/cactus3/init.lua"
-      include "world/immovables/cactus4/init.lua"
-      include "world/immovables/cactus2/init.lua"
+-- RST
+-- .. function:: new_editor_immovable_category{table}
+--
+--    This function adds the definition for a category in the "Immovables" tool.
+--    Only immovables can be in this editor category. The parameter `table` is described below.
+
+      world:new_editor_immovable_category{
+         name = "miscellaneous",
+         descname = _ "Miscellaneous",
+         picture = "world/immovables/ruin5/idle.png",
+         items_per_row = 6,
+      }
+
       include "world/immovables/pebble1/init.lua"
       include "world/immovables/pebble2/init.lua"
       include "world/immovables/pebble3/init.lua"
       include "world/immovables/pebble4/init.lua"
       include "world/immovables/pebble5/init.lua"
       include "world/immovables/pebble6/init.lua"
-      include "world/immovables/manmade/artifacts/artifact00/init.lua"
-      include "world/immovables/manmade/artifacts/artifact01/init.lua"
-      include "world/immovables/manmade/artifacts/artifact02/init.lua"
-      include "world/immovables/manmade/artifacts/artifact03/init.lua"
       include "world/immovables/mushroom1/init.lua"
       include "world/immovables/mushroom2/init.lua"
       include "world/immovables/manmade/snowman/init.lua"
@@ -152,8 +99,48 @@
       include "world/immovables/skeleton2/init.lua"
       include "world/immovables/skeleton4/init.lua"
 
+      -- Artifacts
+      world:new_editor_immovable_category{
+         name = "artifacts",
+         descname = _ "Artifacts" .. "<br>" .. _ "These immovables are used by the win condition “Artifacts”.",
+         picture = "world/immovables/manmade/artifacts/artifact00/idle.png",
+         items_per_row = 6,
+      }
+
+      include "world/immovables/manmade/artifacts/artifact00/init.lua"
+      include "world/immovables/manmade/artifacts/artifact01/init.lua"
+      include "world/immovables/manmade/artifacts/artifact02/init.lua"
+      include "world/immovables/manmade/artifacts/artifact03/init.lua"
+
+      -- Plants
+      world:new_editor_immovable_category{
+         name = "plants",
+         descname = _ "Plants",
+         picture = "world/immovables/cactus3/idle.png",
+         items_per_row = 8,
+      }
+
+      include "world/immovables/grass1/init.lua"
+      include "world/immovables/grass2/init.lua"
+      include "world/immovables/grass3/init.lua"
+      include "world/immovables/bush1/init.lua"
+      include "world/immovables/bush2/init.lua"
+      include "world/immovables/bush3/init.lua"
+      include "world/immovables/bush4/init.lua"
+      include "world/immovables/bush5/init.lua"
+      include "world/immovables/cactus1/init.lua"
+      include "world/immovables/cactus3/init.lua"
+      include "world/immovables/cactus4/init.lua"
+      include "world/immovables/cactus2/init.lua"
 
       -- Standing Stones
+      world:new_editor_immovable_category{
+         name = "standing_stones",
+         descname = _ "Standing Stones",
+         picture = "world/immovables/standing_stones/standing_stone4_desert/idle.png",
+         items_per_row = 4,
+      }
+
       include "world/immovables/standing_stones/standing_stone1_desert/init.lua"
       include "world/immovables/standing_stones/standing_stone1_summer/init.lua"
       include "world/immovables/standing_stones/standing_stone1_wasteland/init.lua"
@@ -178,6 +165,13 @@
       include "world/immovables/standing_stones/standing_stone7/init.lua"
 
       -- Rocks
+      world:new_editor_immovable_category{
+         name = "rocks",
+         descname = _ "Rocks",
+         picture = "world/immovables/rocks/greenland_rocks6/idle.png",
+         items_per_row = 6,
+      }
+
       include "world/immovables/rocks/blackland_rocks1/init.lua"
       include "world/immovables/rocks/blackland_rocks2/init.lua"
       include "world/immovables/rocks/blackland_rocks3/init.lua"
@@ -204,6 +198,41 @@
       include "world/immovables/rocks/winterland_rocks6/init.lua"
 
       -- Trees
+      world:new_editor_immovable_category{
+         name = "trees_dead",
+         descname = _ "Dead Trees",
+         picture = "world/immovables/trees/deadtree2/idle.png",
+         items_per_row = 8,
+      }
+
+      world:new_editor_immovable_category{
+         name = "trees_coniferous",
+         descname = _ "Coniferous Trees",
+         picture = "world/immovables/trees/spruce/old/idle_0.png",
+         items_per_row = 8,
+      }
+
+      world:new_editor_immovable_category{
+         name = "trees_deciduous",
+         descname = _ "Deciduous Trees",
+         picture = "world/immovables/trees/alder/old/idle_0.png",
+         items_per_row = 8,
+      }
+
+      world:new_editor_immovable_category{
+         name = "trees_palm",
+         descname = _ "Palm Trees",
+         picture = "world/immovables/trees/palm_borassus/old/idle_0.png",
+         items_per_row = 8,
+      }
+
+      world:new_editor_immovable_category{
+         name = "trees_wasteland",
+         descname = _ "Wasteland Trees",
+         picture = "world/immovables/trees/umbrella_red/old/idle_0.png",
+         items_per_row = 8,
+      }
+
       include "world/immovables/trees/alder/init.lua"
       include "world/immovables/trees/aspen/init.lua"
       include "world/immovables/trees/beech/init.lua"
@@ -236,7 +265,21 @@
    end)
 
    print_loading_message("┃    Critters", function()
-      -- Herbivores
+
+-- RST
+-- .. function:: new_editor_critter_category{table}
+--
+--    This function adds the definition for a category in the "Animals" tool.
+--    Only critters can be in this editor category.
+
+      world:new_editor_critter_category {
+         name = "critters_herbivores",
+         -- TRANSLATORS: A category in the editor for placing animals on the map.
+         descname = _ "Herbivores",
+         picture = "world/critters/sheep/idle_00.png",
+         items_per_row = 10,
+      }
+
       include "world/critters/bunny/init.lua"
       include "world/critters/sheep/init.lua"
       include "world/critters/wisent/init.lua"
@@ -248,6 +291,14 @@
       include "world/critters/elk/init.lua"
 
       -- Carnivores
+      world:new_editor_critter_category {
+         name = "critters_carnivores",
+         -- TRANSLATORS: A category in the editor for placing animals on the map.
+         descname = _ "Carnivores",
+         picture = "world/critters/fox/idle_00.png",
+         items_per_row = 10,
+      }
+
       include "world/critters/marten/init.lua"
       include "world/critters/badger/init.lua"
       include "world/critters/lynx/init.lua"
@@ -256,6 +307,39 @@
       include "world/critters/brownbear/init.lua"
 
       -- Aquatic animals
+      world:new_editor_critter_category {
+         name = "critters_aquatic",
+         -- TRANSLATORS: A category in the editor for placing animals on the map.
+         descname = _ "Aquatic",
+         picture = "world/critters/duck/idle_00.png",
+         items_per_row = 10,
+      }
+
       include "world/critters/duck/init.lua"
    end)
 end)
+
+-- RST
+--    :arg table: This table contains all the data that the game engine will
+--       add to these editor categories.
+--
+--    **name**
+--        *Mandatory*. A string containing the internal name of this editor category
+--        for reference, e.g.::
+--
+--            name = "summer",
+--
+--    **descname**
+--        *Mandatory*. The translatable display name, e.g.::
+--
+--            descname = _"Summer",
+--
+--    **picture**
+--        *Mandatory*. An image to represent this category in the editor tool's tab, e.g.::
+--
+--            picture = "world/pics/editor_terrain_category_green.png",
+--
+--    **items_per_row**
+--        *Mandatory*. How many items will be displayed in each row by the tool, e.g.::
+--
+--            items_per_row = 6,

=== modified file 'data/world/resources/init.lua'
--- data/world/resources/init.lua	2016-01-25 18:16:48 +0000
+++ data/world/resources/init.lua	2017-09-03 10:57:20 +0000
@@ -1,19 +1,78 @@
+-- RST
+-- .. _lua_world_resources:
+--
+-- Resources
+-- ---------
+--
+-- Resources are mineable map resources.
+-- All resources are defined in ``data/world/resources/init.lua``.
+--
+-- * **Fish** can be placed in water terrain only and be fished by a fisher.
+-- * **Water** can be placed on any non-mountain terrain and be pulled up by a well.
+-- * **Stones**, **Coal**, **Iron** and **Gold** are placed on mountain terrain
+--   and can be dug up by mines.
+--
+-- Which resource can be placed where on the map is defined in each terrain's
+-- ``valid_resources`` table.
+--
+-- The resource names are currently hard-coded in the ``geologist`` worker program
+-- (`bug #1713706 <https://bugs.launchpad.net/widelands/+bug/1713706>`_), so we can't add any detectable resources at the moment.
+
 pics_dir = path.dirname(__file__) .. "pics/"
 
+-- RST
+-- .. function:: new_resource_type{table}
+--
+--    This function adds the definition of a resource to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will add
+--       to this resource. It contains the following entries:
+--
+--    **name**
+--        *Mandatory*. A string containing the internal name of this resource, e.g.::
+--
+--            name = "coal",
+--
+--    **descname**
+--        *Mandatory*. The translatable display name, e.g.::
+--
+--            descname = _"Coal",
+--
+--    **max_amount**
+--        *Mandatory*. The maximum possible amount of this map resource that can
+--        be placed on a map tile, e.g.::
+--
+--            max_amount = 20,
+--
+--    **detectable**
+--        *Mandatory*. Set this to ``true`` if a geologist can find it (water or
+--        mountain resources), and to ``false`` otherwise (fish), e.g.::
+--
+--            detectable = true,
+--
+--    **representative_image**
+--        *Mandatory*. Path to an image file that will represent the resource in menus
+--        etc., e.g.::
+--
+--            representative_image = pics_dir .. "coal4.png",
+--
+--    **editor_pictures**
+--        *Mandatory*. A table of pictures that will indicate the resource amount
+--        on the map, for use in the editor, e.g.::
+--
+--            editor_pictures = {
+--               [5] = pics_dir .. "coal1.png",    -- Use this image for amount 0-5;
+--               [10] = pics_dir .. "coal2.png",   -- Use this image for amount 6-10;
+--               [15] = pics_dir .. "coal3.png",   -- Use this image for amount 11-15;
+--               [1000] = pics_dir .. "coal4.png", -- Use this image for amount > 15;
+--            }
+--
 world:new_resource_type{
-   -- Internal name, must be unique
    name = "coal",
-   -- The name that will be used in UI and translated.
    descname = _ "Coal",
-   -- Maximum possible amount
    max_amount = 20,
-   -- A geologist can find it, otherwise false (see Fish)
    detectable = true,
-   -- This represents the resource in menus etc.
    representative_image = pics_dir .. "coal4.png",
-   -- Picture that is used to indicate the amount of resource on the map
-   -- [5] means amount 0 to 5; next line means amount 6 to 10 and so on
-   -- The picture with highest number is additionally used in ui
    editor_pictures = {
       [5] = pics_dir .. "coal1.png",
       [10] = pics_dir .. "coal2.png",

=== modified file 'data/world/terrains/init.lua'
--- data/world/terrains/init.lua	2017-01-17 08:54:46 +0000
+++ data/world/terrains/init.lua	2017-09-03 10:57:20 +0000
@@ -1,86 +1,173 @@
--- Categories for the editor.
-world:new_editor_terrain_category{
-   name = "summer",
-   descname = _ "Summer",
-   picture = "world/pics/editor_terrain_category_green.png",
-   items_per_row = 6,
-}
-world:new_editor_terrain_category{
-   name = "wasteland",
-   descname = _ "Wasteland",
-   picture = "world/pics/editor_terrain_category_wasteland.png",
-   items_per_row = 6,
-}
-world:new_editor_terrain_category{
-   name = "winter",
-   descname = _ "Winter",
-   picture = "world/pics/editor_terrain_category_winter.png",
-   items_per_row = 6,
-}
-world:new_editor_terrain_category{
-   name = "desert",
-   descname = _ "Desert",
-   picture = "world/pics/editor_terrain_category_desert.png",
-   items_per_row = 6,
-}
+-- RST
+-- .. _lua_world_terrains:
+--
+-- Terrains
+-- --------
+--
+-- Terrains define the basic look of the map, and all terrains are defined in ``data/world/terrains/init.lua``.
+--
+-- .. code-block:: none
+--
+--         *-------*
+--        / \     / \
+--       /   \   /   \
+--      /     \ /     \
+--     *-------*-------*
+--      \     / \     /
+--       \   /   \   /
+--        \ /     \ /
+--         *-------*
+--
+-- Terrain tiles have a triangular shape, and 6 of them will be combined to form a hexagon. Each vertex between the terrains (* in the figure) will form a node that is influenced by the 6 terrains surrounding it, and where other map entities can be placed. You can find more information on the terrains' shape and on how to create textures on the `wiki <https://wl.widelands.org/wiki/HelpTerrains/>`_.
+--
+-- Each terrain tile will also influence some properties for the map entities that are placed on its 3 vertices, like:
+--
+-- * Which resources can go on a map node.
+-- * How well which type of tree will grow on a map node.
+-- * Which map objects can be built on the nodes or move through them.
+
+pics_dir = path.dirname(__file__) .. "pics/"
+
+-- RST
+-- .. function:: new_terrain_type{table}
+--
+--    This function adds the definition of a terrain to the engine.
+--
+--    :arg table: This table contains all the data that the game engine will add
+--       to this terrain. It contains the following entries:
+--
+--    **name**
+--        *Mandatory*. A string containing the internal name of this terrain, e.g.::
+--
+--            name = "summer_meadow1",
+--
+--    **descname**
+--        *Mandatory*. The translatable display name, e.g.::
+--
+--            descname = _"Meadow 1",
+--
+--    **editor_category**
+--        *Mandatory*. The category that is used in the editor tools for placing a
+--        terrain of this type on the map, e.g.::
+--
+--            editor_category = "summer",
+--
+--    **is**
+--        *Mandatory*. The type of this terrain, which determines if the nodes
+--        surrounding the terrain will be walkable or navigable, if mines or buildings
+--        can be built on them, if flags can be built on them, and so on.
+--        The following properties are available:
+--
+--         * ``arable``: Allows building of normal buildings and roads.
+--         * ``mineable``: Allows building of mines and roads.
+--         * ``walkable``: Allows building of flags and roads only.
+--         * ``water``: Nothing can be built here, but ships and aquatic animals can pass.
+--         * ``unreachable``: Nothing can be built here, and nothing can walk on it,
+--           and nothing will grow.
+--         * ``unwalkable``: Nothing can be built here, and nothing can walk on it.
+--
+--        Example::
+--
+--           is = "arable",
+--
+--        *Note: There is currently some interdependency between ``is`` and
+--        ``valid_resources``, so not all combinations are possible. See*
+--        `Bug 1505345 <https://bugs.launchpad.net/widelands/+bug/1505345>`_
+--        *for more information.*
+--
+--    **tooltips**
+--        *Optional*. Additional custom tooltip entries, e.g.::
+--
+--            tooltips = {
+--               -- TRANSLATORS: This is an entry in a terrain tooltip. Try to use 1 word if possible.
+--               _"likes trees",
+--            },
+--
+--    **valid_resources**
+--        *Mandatory*. The list of mineable resources that can be found on this terrain.
+--        Leave this empty (``{}``) if you want no resources on this terrain. Example::
+--
+--            valid_resources = {"water"},
+--
+--        *Note: There is currently some interdependency between ``is`` and
+--        ``valid_resources``, so not all combinations are possible. See*
+--        `Bug #1505345 <https://bugs.launchpad.net/widelands/+bug/1505345/>`_
+--        *for more information.*
+--
+--    **default_resource**
+--        *Mandatory*. A resource type that can always be found on this terrain when
+--        a new game is started, unless the map maker places some resources there via
+--        the editor. Use the empty string
+--        (``""``) if you want no default resource. Example::
+--
+--            default_resource = "water",
+--
+--    **default_resource_amount**
+--        *Mandatory*. The amount of the above default resource that will
+--        automatically be placed on this terrain, e.g.::
+--
+--            default_resource_amount = 10,
+--
+--    **textures**
+--        *Mandatory*. The images used for this terrain. Examples::
+--
+--            textures = { pics_dir .. "summer/meadow1_00.png" }, - A static terrain
+--            textures = path.list_files(pics_dir .. "summer/lava/lava_??.png"), -- An animated terrain
+--
+--    **dither_layer**
+--        *Mandatory*. Terrains will be blended slightly over each other in order
+--        to hide the harsh edges of the triangles. This describes the
+--        `z layer <https://en.wikipedia.org/wiki/Z-order>`_ of a terrain when
+--        rendered next to another terrain. Terrains with a higher value will be
+--        dithered on top of terrains with a lower value. Example::
+--
+--            dither_layer = 340,
+--
+--    **temperature**
+--        *Mandatory*. A terrain affinity constant. These are used to model how well
+--        trees will grow on this terrain. Temperature is in arbitrary units. Example::
+--
+--            temperature = 100,
+--
+--    **humidity**
+--        *Mandatory*. A terrain affinity constant. These are used to model how well
+--        trees will grow on this terrain. Humidity is in percent (1 being very wet).
+--        Example::
+--
+--            humidity = 0.6,
+--
+--    **fertility**
+--        *Mandatory*. A terrain affinity constant. These are used to model how well
+--        trees will grow on this terrain. Fertility is in percent (1 being very
+--        fertile). Example::
+--
+--            fertility = 0.7,
+--
 
 ------------------------
 --  Former greenland  --
 ------------------------
 
-pics_dir = path.dirname(__file__) .. "pics/"
 world:new_terrain_type{
-   -- The internal name of this terrain.
    name = "summer_meadow1",
-
-   -- The name that will be used in UI and translated.
    descname = _ "Meadow 1",
-
-   -- The category for sorting this into menus in the editor.
    editor_category = "summer",
-
-   -- Type of terrain. Describes if the terrain is walkable, swimmable, if
-   -- mines or buildings can be build on it, if flags can be build on it and so
-   -- on.
-   --
-   -- The following properties are available:
-   -- "arable": Allows building of normal buildings and roads
-   -- "mineable": Allows building of mines and roads
-   -- "walkable": Allows building of roads only.
-   -- "water": Nothing can be built here, but ships and aquatic animals can pass
-   -- "unreachable": Nothing can be built here, and nothing can walk on it, and nothing will grow.
-   -- "unwalkable": Nothing can be built here, and nothing can walk on it
    is = "arable",
-
-   -- You can add custom additional tooltip entries here.
    tooltips = {
       -- TRANSLATORS: This is an entry in a terrain tooltip. Try to use 1 word if possible.
       _"likes trees",
    },
 
-   -- The list resources that can be found in this terrain.
    valid_resources = {"water"},
-
-   -- The resources that is always in this terrain (if not overwritten by the
-   -- map maker through the editor) and the amount.
    default_resource = "water",
    default_resource_amount = 10,
 
-   -- The images used for this terrain.
    textures = { pics_dir .. "summer/meadow1_00.png" },
 
-   -- This describes the z layer of the terrain when rendered next to another
-   -- one and blending slightly over it to hide the triangles.
    dither_layer = 340,
 
-   -- Terrain affinity constants. This is used to model how well plants grow on this terrain.
-   -- Temperature is in arbitrary units.
    temperature = 100,
-
-   -- Humidity is in percent (1 being very wet).
    humidity = 0.6,
-
-   -- Fertility is in percent (1 being very fertile).
    fertility = 0.7,
 }
 

=== modified file 'doc/sphinx/extract_rst.py'
--- doc/sphinx/extract_rst.py	2017-08-30 11:58:41 +0000
+++ doc/sphinx/extract_rst.py	2017-09-03 10:57:20 +0000
@@ -31,7 +31,7 @@
 lua_dirs = (
     ('data/scripting', '', 'auxiliary'),
     ('data/scripting/win_conditions', '', 'auxiliary'),
-    ('data/scripting/editor', '', 'lua_world'),
+    ('data/scripting/editor', '', 'lua_world_other'),
     ('data/tribes', '', 'lua_tribes_defining'),
     ('data/tribes/scripting', '', 'lua_tribes_other'),
     ('data/tribes/scripting/mapobject_info', '', 'lua_tribes_other'),
@@ -60,6 +60,15 @@
      'carriers', 'lua_tribes_workers'),
      ('data/tribes/workers/atlanteans/soldier',
      'soldiers', 'lua_tribes_workers'),
+     ('data/world', '', 'lua_world_defining'),
+     ('data/world/critters/badger',
+     'critters', 'lua_world_units'),
+     ('data/world/immovables/bush1',
+     'immovables', 'lua_world_units'),
+     ('data/world/resources',
+     'resources', 'lua_world_units'),
+     ('data/world/terrains',
+     'terrains', 'lua_world_units'),
 )
 
 

=== renamed file 'doc/sphinx/source/lua_world.rst.org' => 'doc/sphinx/source/lua_world.rst'
--- doc/sphinx/source/lua_world.rst.org	2016-08-29 14:02:55 +0000
+++ doc/sphinx/source/lua_world.rst	2017-09-03 10:57:20 +0000
@@ -1,3 +1,5 @@
+.. _toc_lua_world:
+
 Scripts for World
 =================
 
@@ -19,4 +21,6 @@
 .. toctree::
    :maxdepth: 3
 
-REPLACE_ME
+   autogen_toc_lua_world_defining
+   autogen_toc_lua_world_units
+   autogen_toc_lua_world_other

=== added file 'doc/sphinx/source/lua_world_defining.rst.org'
--- doc/sphinx/source/lua_world_defining.rst.org	1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/lua_world_defining.rst.org	2017-09-03 10:57:20 +0000
@@ -0,0 +1,14 @@
+Defining the World
+==================
+
+The world is bootstrapped with the following scripts:
+
+* ``data/world/init.lua``: This file loads all the scripts that define the
+  world. So, if you add a new unit to the world, it needs to be
+  listed in this file.
+* ``data/world/map_generation.lua``: This file is used by the random map generator.
+
+.. toctree::
+   :maxdepth: 3
+
+REPLACE_ME

=== added file 'doc/sphinx/source/lua_world_other.rst.org'
--- doc/sphinx/source/lua_world_other.rst.org	1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/lua_world_other.rst.org	2017-09-03 10:57:20 +0000
@@ -0,0 +1,9 @@
+Other Scripts
+=============
+
+The help files for the editor that describe the world entities are located in ``data/scripting/editor``.
+
+.. toctree::
+   :maxdepth: 3
+
+REPLACE_ME

=== added file 'doc/sphinx/source/lua_world_units.rst.org'
--- doc/sphinx/source/lua_world_units.rst.org	1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/lua_world_units.rst.org	2017-09-03 10:57:20 +0000
@@ -0,0 +1,17 @@
+Defining Units
+==============
+
+A world can have the following types of units:
+
+* **Critters**: Animals that will move around the map at random
+* **Immovables**: Trees, rocks, artifacts and eye candy
+* **Resources**: Mineable map resources like fish, water, coal, ...
+* **Terrains**: The base of the landscape. Meadows, mountains, water...
+
+The definitions for the world's units are located in the subdirectories of
+``data/world``. Each unit needs to have an ``init.lua`` file, which will load the unit to be used in the game.
+
+.. toctree::
+   :maxdepth: 3
+
+REPLACE_ME

=== modified file 'doc/sphinx/source/map_objects.rst'
--- doc/sphinx/source/map_objects.rst	2017-08-28 15:17:11 +0000
+++ doc/sphinx/source/map_objects.rst	2017-09-03 10:57:20 +0000
@@ -5,6 +5,6 @@
    :maxdepth: 3
 
    animations
-   autogen_toc_lua_world
+   lua_world
    lua_tribes
    map_object_programs

=== modified file 'src/scripting/lua_root.cc'
--- src/scripting/lua_root.cc	2017-01-25 18:55:59 +0000
+++ src/scripting/lua_root.cc	2017-09-03 10:57:20 +0000
@@ -294,8 +294,9 @@
 
 .. class:: World
 
-   This offers access to the objects in a the widelands world and allows to add
-   new objects.
+   This offers access to the objects in the Widelands world and allows to add new objects.
+   On how to build the world and adding new objects to it, see
+   :ref:`toc_lua_world`.
 */
 
 const char LuaWorld::className[] = "World";
@@ -376,15 +377,8 @@
 	return 1;
 }
 
-/* RST
-   .. method:: new_resource_type(table)
-
-      Adds a new resource type that can be in the different maps. Takes a
-      single argument, a table with the descriptions for the resource type. See the
-      files in data/world/ for usage examples.
-
-      :returns: :const:`nil`
-*/
+// Documented in data/world/resources/init.lua.
+// See also the World and Tribes section in the Widelands Scripting Reference on the website.
 int LuaWorld::new_resource_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
 		report_error(L, "Takes only one argument.");
@@ -400,15 +394,8 @@
 	return 0;
 }
 
-/* RST
-   .. method:: new_terrain_type(table)
-
-      Adds a new terrain type that can be used in maps. Takes a single
-      argument, a table with the descriptions for the terrain type. See the files in data/world/
-      for usage examples.
-
-      :returns: :const:`nil`
-*/
+// Documented in data/world/terrains/init.lua.
+// See also the World and Tribes section in the Widelands Scripting Reference on the website.
 int LuaWorld::new_terrain_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
 		report_error(L, "Takes only one argument.");
@@ -423,15 +410,8 @@
 	return 0;
 }
 
-/* RST
-   .. method:: new_critter_type(table)
-
-      Adds a new critter type that can be used in maps. Takes a single
-      argument, a table with the description. See the files in data/world/ for usage
-      examples.
-
-      :returns: :const:`nil`
-*/
+// Documented in data/world/critters/badger/init.lua.
+// See also the World and Tribes section in the Widelands Scripting Reference on the website.
 int LuaWorld::new_critter_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
 		report_error(L, "Takes only one argument.");
@@ -445,15 +425,8 @@
 	return 0;
 }
 
-/* RST
-   .. method:: new_immovable_type(table)
-
-      Adds a new immovable type that can be used in maps. Takes a single
-      argument, a table with the description. See the files in data/world/ for usage
-      examples.
-
-      :returns: :const:`nil`
-*/
+// Documented in data/world/immovables/bush1/init.lua.
+// See also the World and Tribes section in the Widelands Scripting Reference on the website.
 int LuaWorld::new_immovable_type(lua_State* L) {
 	if (lua_gettop(L) != 2) {
 		report_error(L, "Takes only one argument.");
@@ -467,15 +440,8 @@
 	return 0;
 }
 
-/* RST
-   .. method:: new_editor_terrain_category(table)
-
-      Adds a new editor category that can be used to classify objects in the
-      world. This will be used to sort them into sub menus in the editor. See
-      usage examples in data/world/.
-
-      :returns: :const:`nil`
-*/
+// Documented in data/world/init.lua.
+// See also the World and Tribes section in the Widelands Scripting Reference on the website.
 int LuaWorld::new_editor_terrain_category(lua_State* L) {
 	if (lua_gettop(L) != 2) {
 		report_error(L, "Takes only one argument.");
@@ -489,13 +455,8 @@
 	return 0;
 }
 
-/* RST
-	.. method:: new_editor_critter_category(table)
-
-		Like :func:`new_editor_terrain_category`, but for immovables.
-
-		:returns: :const:`nil`
-*/
+// Documented in data/world/init.lua.
+// See also the World and Tribes section in the Widelands Scripting Reference on the website.
 int LuaWorld::new_editor_critter_category(lua_State* L) {
 	if (lua_gettop(L) != 2) {
 		report_error(L, "Takes only one argument.");
@@ -509,13 +470,8 @@
 	return 0;
 }
 
-/* RST
-   .. method:: new_editor_immovable_category(table)
-
-      Like :func:`new_editor_terrain_category`, but for immovables.
-
-      :returns: :const:`nil`
-*/
+// Documented in data/world/init.lua.
+// See also the World and Tribes section in the Widelands Scripting Reference on the website.
 int LuaWorld::new_editor_immovable_category(lua_State* L) {
 	if (lua_gettop(L) != 2) {
 		report_error(L, "Takes only one argument.");