widelands-dev team mailing list archive
-
widelands-dev team
-
Mailing list archive
-
Message #11060
[Merge] lp:~widelands-dev/widelands/document_world into lp:widelands
GunChleoc has proposed merging lp:~widelands-dev/widelands/document_world into lp:widelands.
Commit message:
Started adding documentation for world entities.
Requested reviews:
Widelands Developers (widelands-dev)
For more details, see:
https://code.launchpad.net/~widelands-dev/widelands/document_world/+merge/329950
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.
--
Your team Widelands Developers is requested to review the proposed merge of lp:~widelands-dev/widelands/document_world into lp:widelands.
=== 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-08-30 16:50:39 +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.
+--
+-- 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-08-30 16:50:39 +0000
@@ -1,5 +1,101 @@
+-- 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, 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``. 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 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 +110,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-08-30 16:50:39 +0000
@@ -1,3 +1,45 @@
+-- RST
+-- init.lua
+-- --------
+--
+-- World initialization.
+-- All world entities are loaded via this file.
+--
+-- This file also defines the editor categories for world elements so that they
+-- can be added to the editor tools. The available element types are ``terrain``,
+-- ``immovable``, and ``critter``. Editor categories are defined by:
+--
+-- .. function:: new_editor_<element_type>_category{table}
+--
+-- This function adds the definition for an editor category, to be added as a
+-- tab to the tool for ``<element_type>``. Only elements of the given type can
+-- be in the editor category.
+--
+-- :arg table: This table contains all the data that the game engine will add
+-- to this editor category. It contains the following entries:
+--
+-- **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,
+--
+
world = wl.World()
set_textdomain("world")
@@ -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.
+ 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.
+--
+-- :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"
@@ -152,8 +133,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 +199,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 +232,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 +299,23 @@
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.
+--
+-- :arg table: This table contains all the data that the game engine will
+-- add to this editor category. See above.
+ 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 +327,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 +343,14 @@
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)
=== 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-08-30 16:50:39 +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 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-08-30 16:50:39 +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:
+--
+-- * ``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::
+--
+-- 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::
+--
+-- 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-02-20 13:53:01 +0000
+++ doc/sphinx/extract_rst.py 2017-08-30 16:50:39 +0000
@@ -30,7 +30,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'),
@@ -57,6 +57,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-08-30 16:50:39 +0000
@@ -19,4 +19,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-08-30 16:50:39 +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-08-30 16:50:39 +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-08-30 16:50:39 +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 2016-10-14 07:02:10 +0000
+++ doc/sphinx/source/map_objects.rst 2017-08-30 16:50:39 +0000
@@ -5,5 +5,5 @@
:maxdepth: 3
animations
- autogen_toc_lua_world
+ lua_world
lua_tribes
Follow ups
