widelands-dev team mailing list archive

[kaputtnik <somal@xxxxxxxx>]

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

Diff comments:

> 
> === modified file 'data/world/init.lua'
> --- data/world/init.lua	2017-02-12 09:10:57 +0000
> +++ data/world/init.lua	2017-09-01 07:57:51 +0000
> @@ -11,126 +53,65 @@
>     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.
> +--
> +--    :arg table: This table contains all the data that the game engine will
> +--       add to this editor category. See above.

add blank line

> +      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"

add blank line

> +-- 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.
> +--
> +--    :arg table: This table contains all the data that the game engine will
> +--       add to this editor category. See above.
> +      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"
> 
> === 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-01 07:57:51 +0000
> @@ -1,86 +1,162 @@
> --- 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:
> +--

Maybe add here that some values depend also onto the 'valid_resource' value. Not all combinations are possible:
bugs.launchpad.net/widelands/+bug/1505345/comments/1

> +--         * ``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",
> +--
> +--    **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::

See comment for the 'is' value.

> +--
> +--            valid_resources = {"water"},
> +--
> +--    **default_resource**
> +--        *Mandatory*. A resource type that can always be found on this terrain,
> +--        unless overwritten by the map maker via the editor. Use the empty string
> +--        (``""``) if you want no default resource. Example::
> +--

'.. unless overwritten by the map maker via the editor.' is wrong. The default_resource can't be overwritten in the editor afaik.

> +--            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 never shows up in the resources overlay. See also: https://bugs.launchpad.net/widelands/+bug/969873

> +--
> +--            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,
>  }
>  


-- 
https://code.launchpad.net/~widelands-dev/widelands/document_world/+merge/329950
Your team Widelands Developers is requested to review the proposed merge of lp:~widelands-dev/widelands/document_world into lp:widelands.