widelands-dev team mailing list archive
-
widelands-dev team
-
Mailing list archive
-
Message #09996
[Merge] lp:~widelands-dev/widelands/bug-1512093-workers into lp:widelands
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_;
Follow ups
