GunChleoc has proposed merging lp:~widelands-dev/widelands/bug-1512093-workers into lp:widelands.
Commit message: Added sphinx documentation for workers. Requested reviews: Widelands Developers (widelands-dev) For more details, see: https://code.launchpad.net/~widelands-dev/widelands/bug-1512093-workers/+merge/322981 -- Your team Widelands Developers is requested to review the proposed merge of lp:~widelands-dev/widelands/bug-1512093-workers into lp:widelands.
=== modified file 'data/tribes/wares/armor/init.lua' --- data/tribes/wares/armor/init.lua 2016-10-18 09:06:47 +0000 +++ data/tribes/wares/armor/init.lua 2017-04-21 18:29:10 +0000 @@ -10,7 +10,10 @@ -- ``data/tribes/wares/<ware_name>/init.lua``. -- The ware will also need its help texts, which are defined in -- ``data/tribes/wares/<ware_name>/helptexts.lua`` - +-- +-- Fetching the helptext for a ware depends on the current tribe. So, best copy +-- the function out of ``data/tribes/wares/bread_paddle/helptexts.lua`` +-- and use it as a base for creating your ware's helptexts. dirname = path.dirname(__file__) @@ -42,7 +45,7 @@ -- -- **animations**: A table containing all animations for this ware. -- Wares have an "idle" animation. - +-- tribes:new_ware_type { msgctxt = "ware", name = "armor", === modified file 'data/tribes/workers/atlanteans/armorsmith/helptexts.lua' --- data/tribes/workers/atlanteans/armorsmith/helptexts.lua 2015-10-31 12:11:44 +0000 +++ data/tribes/workers/atlanteans/armorsmith/helptexts.lua 2017-04-21 18:29:10 +0000 @@ -1,3 +1,5 @@ +-- The helptext documentation is located in /doc/sphinx/lua_tribes_workers_rst.org + function worker_helptext() -- TRANSLATORS: Helptext for a worker: Armorsmith return pgettext("atlanteans_worker", "Produces armor for the soldiers.") === modified file 'data/tribes/workers/atlanteans/armorsmith/init.lua' --- data/tribes/workers/atlanteans/armorsmith/init.lua 2017-02-12 09:10:57 +0000 +++ data/tribes/workers/atlanteans/armorsmith/init.lua 2017-04-21 18:29:10 +0000 @@ -1,3 +1,5 @@ +-- The basic worker documentation is located in /doc/sphinx/lua_tribes_workers_rst.org + dirname = path.dirname(__file__) animations = { === modified file 'data/tribes/workers/atlanteans/carrier/init.lua' --- data/tribes/workers/atlanteans/carrier/init.lua 2017-02-12 09:10:57 +0000 +++ data/tribes/workers/atlanteans/carrier/init.lua 2017-04-21 18:29:10 +0000 @@ -1,3 +1,18 @@ +-- RST +-- .. _lua_tribes_carriers: +-- +-- Carriers +-- -------- +-- +-- Carriers are specialized workers that carry wares along the roads. +-- Each tribe has a basic human carrier + a second carrier for busy roads - +-- usually a beast of burden. +-- +-- Carriers, like workers, are defined in +-- ``data/tribes/workers/<tribe name>/<worker_name>/init.lua``. +-- The carrier will also need its help texts, which are defined in +-- ``data/tribes/wares/<tribe name>/<worker_name>/helptexts.lua`` + dirname = path.dirname(__file__) animations = { @@ -10,7 +25,22 @@ add_walking_animations(animations, "walk", dirname, "walk", {8, 25}, 10) add_walking_animations(animations, "walkload", dirname, "walkload", {8, 25}, 10) - +-- RST +-- .. function:: new_carrier_type(table) +-- +-- This function adds the definition of a carrier to the engine. +-- +-- :arg table: This table contains all the data that the game engine will add +-- to this carrier. It contains the :ref:`lua_tribes_workers_common`, +-- plus the following additional properties: +-- +-- **ware_hotspot** +-- *Optional*. The x, y coordinates for adjusting the placement of the +-- ware being carried. The default value is ``{0, 15}``. Increase ``x`` +-- to shift the ware to the left and ``y`` to shift it upwards. For example:: +-- +-- ware_hotspot = { -2, 13 }, +-- tribes:new_carrier_type { msgctxt = "atlanteans_worker", --msgctxt = msgctxt, === modified file 'data/tribes/workers/atlanteans/soldier/init.lua' --- data/tribes/workers/atlanteans/soldier/init.lua 2017-02-12 09:10:57 +0000 +++ data/tribes/workers/atlanteans/soldier/init.lua 2017-04-21 18:29:10 +0000 @@ -1,3 +1,17 @@ +-- RST +-- .. _lua_tribes_soldiers: +-- +-- Soldiers +-- -------- +-- +-- Soldiers are specialized workers that can occupy and conquer military sites. +-- Each tribe has exactly one soldier type. +-- +-- Soldiers, like workers, are defined in +-- ``data/tribes/workers/<tribe name>/soldier/init.lua``. +-- The soldier will also need its help texts, which are defined in +-- ``data/tribes/wares/<tribe name>/soldier/helptexts.lua`` + dirname = path.dirname(__file__) animations = { @@ -59,6 +73,123 @@ } add_walking_animations(animations, "walk", dirname, "walk", {20, 34}, 10) +-- RST +-- .. function:: new_soldier_type(table) +-- +-- This function adds the definition of a soldier to the engine. +-- +-- :arg table: This table contains all the data that the game engine will add +-- to this soldier. It contains the :ref:`lua_tribes_workers_common`, +-- plus the following additional properties: +-- +-- **health** +-- This table defines how many health points the soldiers will have. It +-- has the following entries: +-- +-- * ``max_level``: The maximum health level that this soldier can be +-- trained to. +-- * ``base``: The health a level 0 soldier will have. +-- * ``increase_per_level``: The health that a soldier will gain with +-- each level. +-- * ``pictures``: A list of health icons, one for each level. +-- +-- Example:: +-- +-- health = { +-- max_level = 1, +-- base = 13500, +-- increase_per_level = 4000, +-- pictures = path.list_files(dirname .. "health_level?.png"), +-- }, +-- +-- **attack** +-- This table defines how good the soldiers are at attacking. It +-- has the following entries: +-- +-- * ``max_level``: The maximum attack level that this soldier can be +-- trained to. +-- * ``base``: The minimum attack a level 0 soldier will have. During +-- a battle, the engine will pick a value between ``base`` and +-- ``maximum`` at random. +-- * ``maximum``: The maximum attack a level 0 soldier will have. During +-- a battle, the engine will pick a value between ``base`` and +-- ``maximum`` at random. +-- * ``increase_per_level``: The attack that a soldier will gain with +-- each level. +-- * ``pictures``: A list of attack icons, one for each level. +-- +-- Example:: +-- +-- attack = { +-- max_level = 4, +-- base = 1200, +-- maximum = 1600, +-- increase_per_level = 800, +-- pictures = path.list_files(dirname .. "attack_level?.png"), +-- }, +-- +-- **defense** +-- This table defines how good the soldiers are at reducing the damage +-- received by a successful attack. It has the following entries: +-- +-- * ``max_level``: The maximum defense level that this soldier can be +-- trained to. +-- * ``base``: The defense a level 0 soldier will have. +-- * ``increase_per_level``: The defense that a soldier will gain with +-- each level. +-- * ``pictures``: A list of defense icons, one for each level. +-- +-- Example:: +-- +-- defense = { +-- max_level = 2, +-- base = 6, +-- increase_per_level = 8, +-- pictures = path.list_files(dirname .. "defense_level?.png"), +-- }, +-- +-- **evade** +-- +-- This table defines how good the soldiers are at not being hit by an attack. +-- It has the following entries: +-- +-- * ``max_level``: The maximum evade level that this soldier can be +-- trained to. +-- * ``base``: The evade a level 0 soldier will have. +-- * ``increase_per_level``: The evade that a soldier will gain with +-- each level. +-- * ``pictures``: A list of evade icons, one for each level. +-- +-- Example:: +-- +-- evade = { +-- max_level = 2, +-- base = 30, +-- increase_per_level = 17, +-- pictures = path.list_files(dirname .. "evade_level?.png"), +-- }, +-- +-- **Lists of battle animations**: Each soldier needs the following battle animations: +-- * attack_success_w +-- * attack_success_e +-- * attack_failure_w +-- * attack_failure_e +-- * evade_success_w +-- * evade_success_e +-- * evade_failure_w +-- * evade_failure_e +-- * die_w +-- * die_e +-- +-- The engine then picks within the listed animations at random. +-- The lists look like this:: +-- +-- die_w = { +-- "die_w_0", +-- "die_w_1", +-- }, +-- +-- With "die_w_0" and "die_w_1" being members of the "animations" table. tribes:new_soldier_type { msgctxt = "atlanteans_worker", === modified file 'doc/sphinx/extract_rst.py' --- doc/sphinx/extract_rst.py 2016-10-18 07:10:54 +0000 +++ doc/sphinx/extract_rst.py 2017-04-21 18:29:10 +0000 @@ -53,6 +53,10 @@ 'ships', 'lua_tribes_units'), ('data/tribes/wares/armor', 'wares', 'lua_tribes_units'), + ('data/tribes/workers/atlanteans/carrier', + 'carriers', 'lua_tribes_workers'), + ('data/tribes/workers/atlanteans/soldier', + 'soldiers', 'lua_tribes_workers'), ) === modified file 'doc/sphinx/source/animations.rst' --- doc/sphinx/source/animations.rst 2016-11-13 15:23:06 +0000 +++ doc/sphinx/source/animations.rst 2017-04-21 18:29:10 +0000 @@ -1,3 +1,5 @@ +.. _animations: + Animations ========== === modified file 'doc/sphinx/source/lua_tribes_units.rst.org' --- doc/sphinx/source/lua_tribes_units.rst.org 2016-10-18 07:10:54 +0000 +++ doc/sphinx/source/lua_tribes_units.rst.org 2017-04-21 18:29:10 +0000 @@ -16,4 +16,5 @@ :maxdepth: 3 autogen_toc_lua_tribes_buildings + autogen_toc_lua_tribes_workers REPLACE_ME === added file 'doc/sphinx/source/lua_tribes_workers.rst.org' --- doc/sphinx/source/lua_tribes_workers.rst.org 1970-01-01 00:00:00 +0000 +++ doc/sphinx/source/lua_tribes_workers.rst.org 2017-04-21 18:29:10 +0000 @@ -0,0 +1,95 @@ +.. _workers: + +Workers +======= + +Workers are defined in their ``init.lua`` file. They also have a corresponding +``helptexts.lua`` file that contains their help text. +Worker files are placed in ``data/tribes/workers/<tribe_name>/<worker_name>/``. + +Types of Workers +---------------- + +In addition to the basic worker type, Widelands knows about the following sub types: + +.. toctree:: + :maxdepth: 3 + +REPLACE_ME + +.. _lua_tribes_workers_common: + + +Common Worker Properties +------------------------ + +Workers are defined with Lua functions called ``new_worker_type{table}``. The contents of ``table`` depend on the type of worker that you are defining. The common properties shared by all workers are: + + **msgctxt**: The context that Gettext will use to disambiguate the + translations for strings in this table. + + **name**: A string containing the internal name of this worker. + + **descname**: The translatable display name. Use ``pgettext`` with the + ``msgctxt`` above to fetch the string. + + **helptext_script**: The full path to the ``helptexts.lua`` script for this worker. + + **icon**: The full path to the menu icon for this worker. + + **vision_range** + The size of the radius that the worker sees. + + **buildcost** + *Optional*. A table with the wares and workers used by warehouses to + create this worker, containing warename - amount pairs, e.g.:: + + buildcost = { atlanteans_carrier = 1, hammer = 1 } + + **default_target_quantity**: + *Optional*. An int defining the default target quantity for the worker's + tribe's economy. Use this if the worker is produced by a production site + rather than the warehouses. For example, ``default_target_quantity = 10`` + + **experience** + *Optional*. The amount of experience that the worker needs to gather + in order to be transformend into a higher worker type. If `becomes` + is defined, this needs to be set as well. + + **becomes** + *Optional*. The name of the higher worker type that this worker will + transform to after gaining enough experience. If `experience` + is defined, this needs to be set as well. + + **animations**: + A table containing all animations for this worker. + Workers have an "idle" animation. They also have directional animations + called "walk" and "walkload" which are defined with the help of + :func:`add_walking_animations`, plus additional :ref:`animations` used in their + worker programs. The "idle" and "walk" animations are mandatory. + + **programs**: + *Optional*. If the worker leaves the building to do his work, the worker + programs that define which type of space or resource the worker has to find + on the map in order to do his work, and what that work is, including any + animations and sounds played. + See :doc:`worker_program`. + +NOCOM create Worker Program Reference + +Help Texts +---------- + +Each worker has a ``helptexts.lua`` script, which is located in the same directory as its ``init.lua`` script. +The function in this file returns a text that is used for the worker by the Tribal Encyclopedia. + +.. function:: worker_helptext() + + Returns a localized string with the helptext for this worker type. + It needs to be fetched by pgettext, using ``<tribename>_worker`` as the + message context. Example:: + + function worker_helptext() + -- TRANSLATORS: Helptext for a worker: Armorsmith + return pgettext("atlanteans_worker", "Produces armor for the soldiers.") + end === modified file 'src/logic/map_objects/tribes/carrier.cc' --- src/logic/map_objects/tribes/carrier.cc 2017-01-25 18:55:59 +0000 +++ src/logic/map_objects/tribes/carrier.cc 2017-04-21 18:29:10 +0000 @@ -24,10 +24,12 @@ #include "economy/flag.h" #include "economy/road.h" #include "economy/ware_instance.h" +#include "graphic/rendertarget.h" #include "io/fileread.h" #include "io/filewrite.h" #include "logic/game.h" #include "logic/game_data_error.h" +#include "logic/player.h" namespace Widelands { @@ -545,6 +547,34 @@ fw.signed_32(promised_pickup_to_); } +void Carrier::draw_inner(const EditorGameBase& game, + const Vector2f& point_on_dst, + const float scale, + RenderTarget* dst) const { + assert(get_owner() != nullptr); + Worker::draw_inner(game, point_on_dst, scale, dst); + + if (WareInstance const* const carried_ware = get_carried_ware(game)) { + const RGBColor& player_color = get_owner()->get_playercolor(); + const Vector2f hotspot = descr().get_ware_hotspot().cast<float>(); + const Vector2f location( + point_on_dst.x - hotspot.x * scale, point_on_dst.y - hotspot.y * scale); + dst->blit_animation( + location, scale, carried_ware->descr().get_animation("idle"), 0, player_color); + } +} + +CarrierDescr::CarrierDescr(const std::string& init_descname, + const LuaTable& table, + const EditorGameBase& egbase) + : WorkerDescr(init_descname, MapObjectType::CARRIER, table, egbase), + ware_hotspot_(Vector2i(0, 15)) { + if (table.has_key("ware_hotspot")) { + std::unique_ptr<LuaTable> items_table = table.get_table("ware_hotspot"); + ware_hotspot_ = Vector2i(items_table->get_int(1), items_table->get_int(2)); + } +} + /** * Create a new carrier */ === modified file 'src/logic/map_objects/tribes/carrier.h' --- src/logic/map_objects/tribes/carrier.h 2017-01-25 18:55:59 +0000 +++ src/logic/map_objects/tribes/carrier.h 2017-04-21 18:29:10 +0000 @@ -29,16 +29,20 @@ public: CarrierDescr(const std::string& init_descname, const LuaTable& table, - const EditorGameBase& egbase) - : WorkerDescr(init_descname, MapObjectType::CARRIER, table, egbase) { - } + const EditorGameBase& egbase); ~CarrierDescr() override { } + Vector2i get_ware_hotspot() const { + return ware_hotspot_; + } + protected: Bob& create_object() const override; private: + Vector2i ware_hotspot_; + DISALLOW_COPY_AND_ASSIGN(CarrierDescr); }; @@ -66,6 +70,12 @@ static Task const taskRoad; +protected: + void draw_inner(const EditorGameBase& game, + const Vector2f& point_on_dst, + const float scale, + RenderTarget* dst) const override; + private: void find_pending_ware(Game&); int32_t find_closest_flag(Game&); === modified file 'src/logic/map_objects/tribes/worker.cc' --- src/logic/map_objects/tribes/worker.cc 2017-02-28 12:59:39 +0000 +++ src/logic/map_objects/tribes/worker.cc 2017-04-21 18:29:10 +0000 @@ -2550,14 +2550,6 @@ dst->blit_animation( point_on_dst, scale, get_current_anim(), game.get_gametime() - get_animstart(), player_color); - - if (WareInstance const* const carried_ware = get_carried_ware(game)) { - const Vector2f hotspot = descr().get_ware_hotspot().cast<float>(); - const Vector2f location( - point_on_dst.x - hotspot.x * scale, point_on_dst.y - hotspot.y * scale); - dst->blit_animation( - location, scale, carried_ware->descr().get_animation("idle"), 0, player_color); - } } /** === modified file 'src/logic/map_objects/tribes/worker.h' --- src/logic/map_objects/tribes/worker.h 2017-01-25 18:55:59 +0000 +++ src/logic/map_objects/tribes/worker.h 2017-04-21 18:29:10 +0000 @@ -176,10 +176,10 @@ protected: virtual bool is_evict_allowed(); - void draw_inner(const EditorGameBase& game, - const Vector2f& point_on_dst, - const float scale, - RenderTarget* dst) const; + virtual void draw_inner(const EditorGameBase& game, + const Vector2f& point_on_dst, + const float scale, + RenderTarget* dst) const; void draw(const EditorGameBase&, const TextToDraw& draw_text, const Vector2f& field_on_dst, === modified file 'src/logic/map_objects/tribes/worker_descr.cc' --- src/logic/map_objects/tribes/worker_descr.cc 2017-02-28 12:59:39 +0000 +++ src/logic/map_objects/tribes/worker_descr.cc 2017-04-21 18:29:10 +0000 @@ -40,7 +40,6 @@ const LuaTable& table, const EditorGameBase& egbase) : BobDescr(init_descname, init_type, MapObjectDescr::OwnerType::kTribe, table), - ware_hotspot_(Vector2i(0, 15)), buildable_(false), needed_experience_(INVALID_INDEX), becomes_(INVALID_INDEX), @@ -119,10 +118,6 @@ } else { default_target_quantity_ = std::numeric_limits<uint32_t>::max(); } - if (table.has_key("ware_hotspot")) { - items_table = table.get_table("ware_hotspot"); - ware_hotspot_ = Vector2i(items_table->get_int(1), items_table->get_int(2)); - } } WorkerDescr::WorkerDescr(const std::string& init_descname, === modified file 'src/logic/map_objects/tribes/worker_descr.h' --- src/logic/map_objects/tribes/worker_descr.h 2017-01-25 18:55:59 +0000 +++ src/logic/map_objects/tribes/worker_descr.h 2017-04-21 18:29:10 +0000 @@ -62,10 +62,6 @@ return buildcost_; } - Vector2i get_ware_hotspot() const { - return ware_hotspot_; - } - /// How much of the worker type that an economy should store in warehouses. /// The special value std::numeric_limits<uint32_t>::max() means that the /// the target quantity of this ware type will never be checked and should @@ -124,7 +120,6 @@ } protected: - Vector2i ware_hotspot_; Quantity default_target_quantity_; std::string helptext_script_; // The path and filename to the worker's helptext script DirAnimations walk_anims_;
_______________________________________________ Mailing list: https://launchpad.net/~widelands-dev Post to : widelands-dev@lists.launchpad.net Unsubscribe : https://launchpad.net/~widelands-dev More help : https://help.launchpad.net/ListHelp