widelands-dev team mailing list archive
-
widelands-dev team
-
Mailing list archive
-
Message #11031
[Merge] lp:~widelands-dev/widelands/document_worker_program into lp:widelands
GunChleoc has proposed merging lp:~widelands-dev/widelands/document_worker_program into lp:widelands.
Commit message:
Added documentation for worker programs.
Requested reviews:
GunChleoc (gunchleoc)
For more details, see:
https://code.launchpad.net/~widelands-dev/widelands/document_worker_program/+merge/329696
This documentation is to replace https://wl.widelands.org/wiki/WorkerCommands/, which was never finished.
Also hooked the production program reference into the TOC.
The changes in implementation.rst are just fixed line endings, plus a code highlighting command at the top of the file.
--
Your team Widelands Developers is subscribed to branch lp:~widelands-dev/widelands/document_worker_program.
=== 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-28 15:18:54 +0000
@@ -20,6 +20,7 @@
('src/scripting/lua_game.cc', 'autogen_wl_game.rst'),
('src/scripting/lua_ui.cc', 'autogen_wl_ui.rst'),
('src/scripting/lua_globals.cc', 'autogen_globals.rst'),
+ ('src/logic/map_objects/tribes/worker_program.cc', 'autogen_tribes_worker_programs.rst'),
)
# These directories are scanned without knowing which file
=== modified file 'doc/sphinx/source/animations.rst'
--- doc/sphinx/source/animations.rst 2017-08-27 08:21:51 +0000
+++ doc/sphinx/source/animations.rst 2017-08-28 15:18:54 +0000
@@ -122,7 +122,7 @@
**walkload**
*Optional*. A directional animation. The worker is walking while carrying something.
-Any further animations like e.g. "plant", "harvest", or "breed" will be referenced in the ``programs table``, under the ``animation`` command.
+Any further animations like e.g. "plant", "harvest", or "breed" will be referenced in the :ref:`tribes_worker_programs`, under the ``animation`` command.
For example, a fisher could look like this::
=== modified file 'doc/sphinx/source/conf.py'
--- doc/sphinx/source/conf.py 2017-07-04 19:17:39 +0000
+++ doc/sphinx/source/conf.py 2017-08-28 15:18:54 +0000
@@ -86,6 +86,8 @@
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
+highlight_language = 'lua'
+
# -- Options for HTML output ---------------------------------------------------
=== modified file 'doc/sphinx/source/implementation.rst'
--- doc/sphinx/source/implementation.rst 2013-10-19 10:42:47 +0000
+++ doc/sphinx/source/implementation.rst 2017-08-28 15:18:54 +0000
@@ -1,11 +1,13 @@
+.. highlight:: default
+
Implementation Notes
====================
This section is for developers who want to add more features to the Lua
support in widelands (or that want to track down bugs). This contains notes
-about how certain things are implemented and how to add to it.
+about how certain things are implemented and how to add to it.
-.. Note::
+.. Note::
This section is not for scenario designers, only for developers
working directly on widelands.
@@ -17,7 +19,7 @@
The scripting interface is defined in ``scripting/scripting.h``. It consists
of the two classes LuaInterface for running scripts and LuaCouroutine which
wraps a Lua coroutine. The Lua interface is accessed via the lua() function in
-Editor_Game_Base.
+Editor_Game_Base.
There are two game commands for lua: ``Cmd_LuaScript`` and
``Cmd_LuaCoroutine``. The first one is only used to enqueue the initial
@@ -58,7 +60,7 @@
const char L_Player::className[] = "Player"; // Name of this class
const MethodType<L_Player> L_Player::Methods[] = {
- METHOD(L_Player, __eq), // compare operator
+ METHOD(L_Player, __eq), // compare operator
METHOD(L_Player, place_flag), // a method called place_flag
{0, 0}, // end of methods table
};
@@ -85,18 +87,18 @@
Luna Classes need even more boilerplate to work correctly. Firstly, they must
define a function ``get_modulename`` that returns a ``const char *`` which
will be the submodule name where this class is registered. For our example,
-Player would return ``"game"`` because it is defined in ``wl.game``.
+Player would return ``"game"`` because it is defined in ``wl.game``.
The class must also define two constructors, one that takes no arguments and
is only used to create a empty class that is created for unpersisting. And a
second one that takes a ``lua_State *`` that is called when the construction
is requested from Lua, that is if ``wl.game.Player()`` is called. Some (most?)
classes can't be constructed from Lua and should then answer with
-``report_error()``.
+``report_error()``.
En plus, a function ``__persist(lua_State *)`` and a function
``__unpersist(lua_State *)`` must be defined. They are discussed in the next
-section.
+section.
.. _Luna: http://lua-users.org/wiki/SimplerCppBinding
@@ -104,10 +106,10 @@
-----------
When a savegame is created, the current environment of Lua is persisted. For
-this, I used a library called Eris_.
+this, I used a library called Eris_.
.. _Eris: https://github.com/fnuecke
-
+
The global environment is persisted into the file map/globals.dump. Everything
is persisted except of the Lua build-in functions and everything in the ``wl``
table and some of our own global functions. Those are c-functions that can not
@@ -115,7 +117,7 @@
everything in the auxiliary scripts are saved to disk, so save games only
depend on the API defined inside the Widelands.
-Coroutines are persisted in their ``Cmd_LuaCoroutine`` package.
+Coroutines are persisted in their ``Cmd_LuaCoroutine`` package.
Luna classes have to implement two functions to be properly persistable:
@@ -139,20 +141,20 @@
*)`` to the Map_Map_Object_Loader and ``get_mos(lua_State *)`` to the
Map_Map_Object_Saver. These function return 0 when not called in
``__persist`` and ``__unpersist``.
-
+
Testing
-------
Lua support is currently tested in two different scenarios. Both life in
``src/scripting/test`` and they work essentially the same: they are normal
-scenarios which contain a Lua unittest framework named lunit_ that the
+scenarios which contain a Lua unittest framework named lunit_ that the
author agreed to be used in widelands like that. The scripts than use various
-Lua functions and check that they do the expected things.
+Lua functions and check that they do the expected things.
If you add new features to the Lua support of Widelands, consider also adding
tests in the appropriate places in the test suite. This guarantees that nothing
unexpected happens in scenarios and it will show the most common bugs quite
-easily.
+easily.
.. _lunit: http://www.nessie.de/mroth/lunit/
@@ -173,7 +175,7 @@
#### Test Suite finished.
353 Assertions checked. All Tests passed!
-
+
If the test suite fails, widelands will be kept running and the error message
of the failed test will be visible in the output. This is then a bug and
should be reported.
@@ -185,7 +187,7 @@
between different versions. First, you need to run it as scenario::
$ ./widelands --scenario=src/scripting/test/persistence.wmf
-
+
This will result in the creation of various Lua objects. Widelands will then
immediately safe the game as ``lua_persistence.wgf`` and exit. You can then
load this game::
=== modified file 'doc/sphinx/source/lua_tribes_workers.rst.org'
--- doc/sphinx/source/lua_tribes_workers.rst.org 2017-07-03 10:16:59 +0000
+++ doc/sphinx/source/lua_tribes_workers.rst.org 2017-08-28 15:18:54 +0000
@@ -1,5 +1,3 @@
-.. _workers:
-
Workers
=======
@@ -19,7 +17,6 @@
.. _lua_tribes_workers_common:
-
Common Worker Properties
------------------------
@@ -69,13 +66,10 @@
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
+ *Optional*. If the worker leaves the building to do his work, the :ref:`tribes_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.
-TODO(GunChleoc): create Worker Program Reference
-
Help Texts
----------
=== added file 'doc/sphinx/source/map_object_programs.rst'
--- doc/sphinx/source/map_object_programs.rst 1970-01-01 00:00:00 +0000
+++ doc/sphinx/source/map_object_programs.rst 2017-08-28 15:18:54 +0000
@@ -0,0 +1,14 @@
+Programs
+========
+
+Some map object will have special programs that define their behavior.
+You can describe these programs in their ``init.lua`` files, in the ``programs``
+table. Map objects that can have programs are:
+
+.. toctree::
+ :maxdepth: 3
+
+ Production Sites <productionsite_program>
+ Workers <autogen_tribes_worker_programs>
+
+The programs for Immovables haven't been documented yet.
=== 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-28 15:18:54 +0000
@@ -7,3 +7,4 @@
animations
autogen_toc_lua_world
lua_tribes
+ map_object_programs
=== modified file 'doc/sphinx/source/productionsite_program.rst'
--- doc/sphinx/source/productionsite_program.rst 2017-08-27 08:21:51 +0000
+++ doc/sphinx/source/productionsite_program.rst 2017-08-28 15:18:54 +0000
@@ -76,6 +76,7 @@
The different command types and the parameters that they take are explained below.
+.. highlight:: default
Command Types
^^^^^^^^^^^^^
=== modified file 'src/logic/map_objects/tribes/worker_program.cc'
--- src/logic/map_objects/tribes/worker_program.cc 2017-01-25 18:55:59 +0000
+++ src/logic/map_objects/tribes/worker_program.cc 2017-08-28 15:18:54 +0000
@@ -30,6 +30,53 @@
#include "sound/sound_handler.h"
namespace Widelands {
+/* RST
+.. _tribes_worker_programs:
+
+Worker Programs
+===============
+
+Worker programs are defined in the ``programs`` subtable specified in calls to
+:ref:`tribes:new_worker_type <lua_tribes_workers_common>`.
+Each worker program is a Lua table in itself and defined as a series of command strings.
+Commands can also have parameters, which are separated from each other by a blank space.
+These parameters can also have values, which are separated from the parameter name by a colon (:).
+The table looks like this::
+
+ programs = {
+ program_name1 = {
+ "command1 parameter1:value1 parameter2:value2",
+ "command2 parameter1",
+ "return"
+ },
+ program_name2 = {
+ "command3",
+ "command4 parameter1 parameter2 parameter3",
+ "return"
+ }
+ },
+
+The available programs are:
+
+- `createware`_
+- `mine`_
+- `breed`_
+- `setbobdescription`_
+- `findobject`_
+- `findspace`_
+- `walk`_
+- `animation`_
+- `return`_
+- `object`_
+- `plant`_
+- `create_bob`_
+- `object remove`_
+- `geologist`_
+- `geologist_find`_
+- `scout`_
+- `play_sound`_
+- `construct`_
+*/
const WorkerProgram::ParseMap WorkerProgram::parsemap_[] = {
{"mine", &WorkerProgram::parse_mine},
@@ -93,11 +140,27 @@
}
}
+/* RST
+createware
+^^^^^^^^^^
+.. function:: createware \<ware_name\>
+
+ :arg string ware_name: The ware type to create, e.g. ``wheat``.
+
+ The worker will create and carry a ware of the given type. Example::
+
+ harvest = {
+ "findobject attrib:ripe_wheat radius:2",
+ "walk object",
+ "play_sound sound/farm scythe 220",
+ "animation harvesting 10000",
+ "object harvest",
+ "animation gathering 4000",
+ "createware wheat", -- Create 1 wheat and start carrying it
+ "return"
+ },
+*/
/**
- * createware \<waretype\>
- *
- * The worker will create and carry a ware of the given type.
- *
* iparam1 = ware index
*/
void WorkerProgram::parse_createware(Worker::Action* act, const std::vector<std::string>& cmd) {
@@ -108,12 +171,30 @@
act->iparam1 = tribes_.safe_ware_index(cmd[1]);
}
+/* RST
+mine
+^^^^
+.. function:: mine \<resource_name\> \<area\>
+
+ :arg string resource_name: The map resource to mine, e.g. ``fish``.
+
+ :arg int area: The radius that is scanned for decreasing the map resource, e.g. ``1``.
+
+ Mine on the current coordinates that the worker has walked to for resources decrease.
+ Example::
+
+ fish = {
+ "findspace size:any radius:7 resource:fish",
+ "walk coords",
+ "play_sound sound/fisher fisher_throw_net 192",
+ "mine fish 1", -- Remove a fish in an area of 1
+ "animation fishing 3000",
+ "play_sound sound/fisher fisher_pull_net 192",
+ "createware fish",
+ "return"
+ },
+*/
/**
- * mine \<resource\> \<area\>
- *
- * Mine on the current coordinates (from walk or so) for resources decrease,
- * go home
- *
* iparam1 = area
* sparam1 = resource
*/
@@ -130,12 +211,27 @@
throw wexception("Bad area '%s'", cmd[2].c_str());
}
+/* RST
+breed
+^^^^^
+.. function:: breed \<resource_name\> \<area\>
+
+ :arg string resource_name: The map resource to breed, e.g. ``fish``.
+
+ :arg int area: The radius that is scanned for increasing the map resource, e.g. ``1``.
+
+ Breed a resource on the current coordinates that the worker has walked to for
+ resources increase. Example::
+
+ breed = {
+ "findspace size:any radius:7 breed resource:fish",
+ "walk coords",
+ "animation freeing 3000",
+ "breed fish 1", -- Add a fish in an area of 1
+ "return"
+ },
+*/
/**
- * breed \<resource\> \<area\>
- *
- * Breed on the current coordinates (from walk or so) for resource increase,
- * go home
- *
* iparam1 = area
* sparam1 = resource
*/
@@ -152,12 +248,28 @@
throw wexception("Bad area '%s'", cmd[2].c_str());
}
+/* RST
+setbobdescription
+^^^^^^^^^^^^^^^^^
+.. function:: setbobdescription \<bob_name\> [\<bob_name\> ...]
+
+ :arg string bob_name: The bob type to add to the selection. Specify as many bob
+ types as you want.
+
+ Randomly select a bob name that can be used in subsequent commands,
+ e.g. create_bob. Used for releasing animals. Example::
+
+ release = {
+ "setbobdescription wildboar stag sheep", -- A wildboar, stag or sheep will be selected
+ "findspace size:any radius:3",
+ "walk coords",
+ "animation releasein 2000",
+ "create_bob",
+ "animation releaseout 2000",
+ "return"
+ },
+*/
/**
- * setbobdescription \<bob name\> \<bob name\> ...
- *
- * Randomly select a bob name that can be used in subsequent commands
- * (e.g. create_bob).
- *
* sparamv = possible bobs
*/
void WorkerProgram::parse_setbobdescription(Worker::Action* act,
@@ -171,22 +283,39 @@
act->sparamv.push_back(cmd[i]);
}
+/* RST
+findobject
+^^^^^^^^^^
+.. function:: findobject radius:\<distance\> [type:\<map_object_type\>] [attrib:\<attribute\>]
+
+ :arg int radius: Search for an object within the given radius around the worker.
+ :arg string type: The type of map object to search for. Defaults to ``immovable``.
+ :arg string attrib: The attribute that the map object should possess.
+
+ Find and select an object based on a number of predicates, which can be specified
+ in arbitrary order. The object can then be used in other commands like ``walk``
+ or ``object``. Examples::
+
+ cut_granite = {
+ "findobject attrib:rocks radius:6", -- Find rocks on the map within a radius of 6 from your building
+ "walk object", -- Now walk to those rocks
+ "play_sound sound/atlanteans/cutting stonecutter 192",
+ "animation hacking 12000",
+ "object shrink",
+ "createware granite",
+ "return"
+ },
+
+ hunt = {
+ "findobject type:bob radius:13 attrib:eatable", -- Find an eatable bob (animal) within a radius of 13 from your building
+ "walk object", -- Walk to where the animal is
+ "animation idle 1500",
+ "object remove",
+ "createware meat",
+ "return"
+ },
+*/
/**
- * findobject key:value key:value ...
- *
- * Find and select an object based on a number of predicates.
- * The object can be used in other commands like walk or object.
- *
- * Predicates:
- * radius:\<dist\>
- * Find objects within the given radius
- *
- * attrib:\<attribute\> (optional)
- * Find objects with the given attribute
- *
- * type:\<what\> (optional, defaults to immovable)
- * Find only objects of this type
- *
* iparam1 = radius predicate
* iparam2 = attribute predicate (if >= 0)
* sparam1 = type
@@ -226,36 +355,68 @@
workarea_info_[act->iparam1].insert(" findobject");
}
+/* RST
+findspace
+^^^^^^^^^
+.. function:: findspace size:\<plot\> radius:\<distance\> [breed] [resource:\<name\>] [avoid:\<immovable_attribute\>] [space]
+
+ :arg string size: The size or building plot type of the free space.
+ The possible values are:
+
+ * ``any``: Any size will do.
+ * ``build``: Any building plot.
+ * ``small``: Small building plots only.
+ * ``medium``: Medium building plots only.
+ * ``big``: Big building plots only.
+ * ``mine``: Mining plots only.
+ * ``port``: Port spaces only.
+
+ :arg int radius: Search for map fields within the given radius around the worker.
+
+ :arg empty breed: Used in front of ``resource`` only: Also accept fields where the
+ resource has been depleted. Use this when looking for a place for breeding.
+
+ :arg string resource: A resource to search for. This is mainly intended for
+ fishers and suchlike, for non-detectable resources and default resources.
+
+ :arg string avoid: A field containing an immovable that has this attribute will
+ not be used.
+
+ :arg empty space: Find only fields that are walkable in such a way that all
+ neighbors are also walkable (an exception is made if one of the neighboring
+ fields is owned by this worker's location).
+
+ Find a map field based on a number of predicates.
+ The field can then be used in other commands like ``walk``. Examples::
+
+ breed = {
+ "findspace size:any radius:7 breed resource:fish", -- Find any field that can have fish in it for adding a fish to it below
+ "walk coords",
+ "animation freeing 3000",
+ "breed fish 1",
+ "return"
+ },
+
+ plant = {
+ "findspace size:any radius:5 avoid:field", -- Don't get in the way of the farmer's crops when planting trees
+ "walk coords",
+ "animation dig 2000",
+ "animation planting 1000",
+ "plant attrib:tree_sapling",
+ "animation water 2000",
+ "return"
+ },
+
+ plant = {
+ "findspace size:any radius:2 space", -- The farmer will want to walk to this field again later for harvesting his crop
+ "walk coords",
+ "animation planting 4000",
+ "plant tribe:field_tiny",
+ "animation planting 4000",
+ "return",
+ },
+*/
/**
- * findspace key:value key:value ...
- *
- * Find a field based on a number of predicates.
- * The field can later be used in other commands, e.g. walk.
- *
- * Predicates:
- * radius:\<dist\>
- * Search for fields within the given radius around the worker.
- *
- * size:[any|build|small|medium|big|mine|port]
- * Search for fields with the given amount of space.
- *
- * breed
- * in resource:\<resname\>, also accept fields where the resource has been
- * depleted. Use this when looking for a place for breeding. Should be used
- * before resource:\<resname\>
- *
- * resource:\<resname\>
- * Resource to search for. This is mainly intended for fisher and
- * therelike (non detectable Resources and default resources)
- *
- * avoid:\<immovable attribute>
- * a field containing an immovable with that immovable should not be used
- *
- * space
- * Find only fields that are walkable such that all neighbours
- * are also walkable (an exception is made if one of the neighbouring
- * fields is owned by this worker's location).
- *
* iparam1 = radius
* iparam2 = FindNodeSize::sizeXXX
* iparam3 = whether the "space" flag is set
@@ -325,15 +486,50 @@
workarea_info_[act->iparam1].insert(" findspace");
}
+/* RST
+walk
+^^^^
+.. function:: walk \<destination_type\>
+
+ :arg string destination_type: Defines where to walk to. Possible destinations are:
+
+ * ``object``: Walk to a previously found and selected object.
+ * ``coords``: Walk to a previously found and selected field/coordinate.
+ * ``object-or-coords``: Walk to a previously found and selected object if present;
+ otherwise to previously found and selected field/coordinate.
+
+ Walk to a previously selected destination. Examples::
+
+ plant = {
+ "findspace size:any radius:2",
+ "walk coords", -- Walk to the space found by the command above
+ "animation planting 4000",
+ "plant tribe:blackrootfield_tiny",
+ "animation planting 4000",
+ "return"
+ },
+
+ harvest = {
+ "findobject attrib:ripe_blackroot radius:2",
+ "walk object", -- Walk to the blackroot field found by the command above
+ "animation harvesting 10000",
+ "object harvest",
+ "animation gathering 2000",
+ "createware blackroot",
+ "return"
+ },
+
+ buildship = {
+ "walk object-or-coords", -- Walk to coordinates from 1. or to object from 2.
+ "plant tribe:barbarians_shipconstruction unless object", -- 2. This will create an object for us if we don't have one yet
+ "play_sound sound/sawmill sawmill 230",
+ "animation work 500",
+ "construct", -- 1. This will find a space for us if no object has been planted yet
+ "animation work 5000",
+ "return"
+ },
+*/
/**
- * walk \<where\>
- *
- * Walk to a previously selected destination. where can be one of:
- * object walk to a previously found and selected object
- * coords walk to a previously found and selected field/coordinate
- * object-or-coords walk to a previously found and selected object if
- * present; otherwise to previously found and selected coordinate
- *
* iparam1 = walkXXX
*/
void WorkerProgram::parse_walk(Worker::Action* act, const std::vector<std::string>& cmd) {
@@ -352,14 +548,28 @@
throw wexception("Bad walk destination '%s'", cmd[1].c_str());
}
+/* RST
+animation
+^^^^^^^^^
+.. function:: animation \<name\> \<duration\>
+
+ :arg string name: The name of the animation.
+ :arg int duration: The time in milliseconds for which the animation will be played.
+
+ Play the given animation for the given duration. Example::
+
+ plantvine = {
+ "findspace size:any radius:1",
+ "walk coords",
+ "animation dig 2000", -- Play a digging animation for 2 seconds.
+ "plant tribe:grapevine_tiny",
+ "animation planting 3000", -- Play a planting animation for 3 seconds.
+ "return"
+ },
+*/
/**
- * animation \<name\> \<duration\>
- *
- * Play the given animation for the given amount of time.
- *
* iparam1 = anim id
* iparam2 = duration
- *
*/
void WorkerProgram::parse_animation(Worker::Action* act, const std::vector<std::string>& cmd) {
char* endp;
@@ -383,9 +593,19 @@
throw GameDataError("animation duration must be positive");
}
+/* RST
+return
+^^^^^^
+.. function:: return
+
+ Return home and then drop any ware we're carrying onto our building's flag. Example::
+
+ scout = {
+ "scout 15 75000",
+ "return" -- Go home
+ }
+*/
/**
- * Return home, drop an ware we're carrying onto our building's flag.
- *
* iparam1 = 0: don't drop ware on flag, 1: do drop ware on flag
*/
void WorkerProgram::parse_return(Worker::Action* act, const std::vector<std::string>&) {
@@ -393,11 +613,28 @@
act->iparam1 = 1; // drop a ware on our owner's flag
}
+/* RST
+object
+^^^^^^
+.. function:: object \<program_name\>
+
+ :arg string program_name: The name of the program to be executed.
+
+ Cause the currently selected object to execute its given program. Example::
+
+ chop = {
+ "findobject attrib:tree radius:10",
+ "walk object",
+ "play_sound sound/woodcutting fast_woodcutting 250",
+ "animation hacking 10000",
+ "play_sound sound/woodcutting tree-falling 130",
+ "object fall", -- Cause the tree to fall
+ "animation idle 2000",
+ "createware log",
+ "return"
+ }
+*/
/**
- * object \<command\>
- *
- * Cause the currently selected object to execute the given program.
- *
* sparam1 = object command name
*/
void WorkerProgram::parse_object(Worker::Action* act, const std::vector<std::string>& cmd) {
@@ -408,12 +645,53 @@
act->sparam1 = cmd[1];
}
+/* RST
+plant
+^^^^^
+.. function:: plant \<immmovable_type\> [\<immovable_type\> ...] [unless object]
+
+ :arg string immovable_type: The immovable to be planted. This can be specified
+ in two different ways:
+
+ * ``attrib:<attribute>``: Select at random any immovable that has this attribute.
+ * ``tribe:<immovable_name>``: Name a specific immovable to be planted.
+
+ :arg empty unless object: Do not plant the immovable if it already exists at
+ the current position.
+
+ Plant one of the given immovables on the current position, taking into account
+ the fertility of the area. Examples::
+
+ plant = {
+ "findspace size:any radius:5 avoid:field",
+ "walk coords",
+ "animation dig 2000",
+ "animation planting 1000",
+ "plant attrib:tree_sapling", -- Plant any random sapling tree
+ "animation water 2000",
+ "return"
+ },
+
+ plant = {
+ "findspace size:any radius:2 space",
+ "walk coords",
+ "animation planting 4000",
+ "plant tribe:field_tiny", -- Plant the tiny field immovable that the worker's tribe knows about
+ "animation planting 4000",
+ "return",
+ },
+
+ buildship = {
+ "walk object-or-coords",
+ "plant tribe:empire_shipconstruction unless object", -- Only create a shipconstruction if we don't already have one
+ "play_sound sound/sawmill sawmill 230",
+ "animation work 500",
+ "construct",
+ "animation work 5000",
+ "return"
+ }
+*/
/**
- * plant \<immmovable type\> \<immovable type\> ... [unless object]
- *
- * Plant one of the given immovables on the current position taking into
- * account the fertility of the area.
- *
* sparamv list of object names
* iparam1 one of plantXXX
*/
@@ -456,27 +734,66 @@
}
}
-/**
- * Plants a bob (critter usually, maybe also worker later on). The immovable
- * type must have been selected by a previous command (i.e. setbobdescription).
- */
+/* RST
+create_bob
+^^^^^^^^^^
+.. function:: create_bob
+
+ Adds a bob (usually an animal) to the map at the worker's current location.
+ The list of possible bobs must have been selected by a previous command. Example::
+
+ release = {
+ "setbobdescription wildboar stag sheep", -- We want to release a wildboar, stag or sheep into the wild
+ "findspace size:any radius:3",
+ "walk coords",
+ "animation releasein 2000",
+ "create_bob", -- Now release a wildboar, stag or sheep into the wild
+ "animation releaseout 2000",
+ "return"
+ }
+*/
void WorkerProgram::parse_create_bob(Worker::Action* act, const std::vector<std::string>&) {
act->function = &Worker::run_create_bob;
}
-/**
- * Simply remove the currently selected object - make no fuss about it.
- */
+/* RST
+object remove
+^^^^^^^^^^^^^
+.. function:: object remove
+
+ Remove the currently selected object. Example::
+
+ hunt = {
+ "findobject type:bob radius:13 attrib:eatable", -- Select an object to remove
+ "walk object",
+ "animation idle 1000",
+ "object remove", -- The selected eatable map object has been hunted, so remove it from the map
+ "createware meat",
+ "return"
+ }
+*/
void WorkerProgram::parse_removeobject(Worker::Action* act, const std::vector<std::string>&) {
act->function = &Worker::run_removeobject;
}
+/* RST
+geologist
+^^^^^^^^^
+.. function:: geologist \<repetitions\> \<radius\> \<program_name\>
+
+ :arg int repetitions: The number of times that the geologist will move to a
+ different spot on the map to execute ``program_name``.
+
+ :arg int radius: The radius of map fields for the geologist not to stray from.
+
+ Walk around the starting point randomly within a certain radius, and execute
+ your ``program_name`` for some of the fields. Example::
+
+ expedition = {
+ "geologist 15 5 search"
+ },
+*/
/**
- * geologist \<repeat #\> \<radius\> \<subcommand\>
- *
- * Walk around the starting point randomly within a certain radius,
- * and execute the subcommand for some of the fields.
- *
* iparam1 = maximum repeat #
* iparam2 = radius
* sparam1 = subcommand
@@ -500,10 +817,22 @@
act->sparam1 = cmd[3];
}
-/**
- * Check resources at the current position, and plant a marker object
- * when possible.
- */
+/* RST
+geologist_find
+^^^^^^^^^^^^^^
+.. function:: geologist_find
+
+ Check the current position for map resources (e.g. coal or water), and plant
+ a marker object when possible. Example::
+
+ search = {
+ "animation hacking 5000",
+ "animation idle 2000",
+ "play_sound sound/hammering geologist_hammer 192",
+ "animation hacking 3000",
+ "geologist_find" -- Plant a resource marker at the current location, according to what has been found.
+ }
+*/
void WorkerProgram::parse_geologist_find(Worker::Action* act, const std::vector<std::string>& cmd) {
if (cmd.size() != 1)
throw wexception("Usage: geologist_find");
@@ -511,11 +840,23 @@
act->function = &Worker::run_geologist_find;
}
+/* RST
+scout
+^^^^^
+.. function:: scout \<radius\> \<time\>
+
+ :arg int radius: The radius of map fields for the scout to explore.
+
+ :arg int time: The time in milliseconds that the scout will spend scouting.
+
+ Sends a scout out to run around scouting the area. Example::
+
+ scout = {
+ "scout 15 75000", -- Scout within a radius of 15 for 75 seconds
+ "return"
+ },
+*/
/**
- * scout \<radius\> \<time\>
- *
- * Sends the scout out to run around scouting the area
- *
* iparam1 = radius
* iparam2 = time
*/
@@ -528,6 +869,32 @@
act->function = &Worker::run_scout;
}
+/* RST
+play_sound
+^^^^^^^^^^
+.. function:: play_sound \<sound_dir\> \<sound_name\> [priority]
+
+ :arg string sound_dir: The directory (folder) that the sound files are in,
+ relative to the data directory.
+ :arg string sound_name: The name of the particular sound to play.
+ There can be multiple sound files to select from at random, e.g.
+ for `scythe`, we can have `scythe_00.ogg`, `scythe_01.ogg` ...
+
+ :arg int priority: The priority to give this sound. Maximum priority is 255.
+
+ Play a sound effect. Example::
+
+ harvest = {
+ "findobject attrib:ripe_wheat radius:2",
+ "walk object",
+ "play_sound sound/farm scythe 220", -- Almost certainly play a swishy harvesting sound
+ "animation harvesting 10000",
+ "object harvest",
+ "animation gathering 4000",
+ "createware wheat",
+ "return"
+ }
+*/
void WorkerProgram::parse_play_sound(Worker::Action* act, const std::vector<std::string>& cmd) {
if (cmd.size() < 3 || cmd.size() > 4)
throw wexception("Usage: play_sound <sound_dir> <sound_name> [priority]");
@@ -541,6 +908,24 @@
atoi(cmd[3].c_str());
}
+/* RST
+construct
+^^^^^^^^^
+.. function:: construct
+
+ Give the ware currently held by the worker to the immovable object for construction.
+ This is used in ship building. Example::
+
+ buildship = {
+ "walk object-or-coords", -- Walk to coordinates from 1. or to object from 2.
+ "plant tribe:barbarians_shipconstruction unless object", -- 2. This will create an object for us if we don't have one yet
+ "play_sound sound/sawmill sawmill 230",
+ "animation work 500",
+ "construct", -- 1. Add the current ware to the shipconstruction. This will find a space for us if no shipconstruction object has been planted yet
+ "animation work 5000",
+ "return"
+ },
+*/
/**
* construct
*
References
