:mod:`wl` ====================== .. module:: wl :synopsis: Base classes which allow access to all widelands internals. .. moduleauthor:: The Widelands development team .. currentmodule:: wl Module Classes ^^^^^^^^^^^^^^^^ Game ----- .. graphviz:: :alt: Dependency graph for class: Game graph Game { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Game [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] EditorGameBase [shape=house, href="../autogen_wl_bases/index.html#editorgamebase", target="_parent"] EditorGameBase -- Game } .. class:: Game Child of: :class:`wl.bases.EditorGameBase` The root class to access the game internals. Use ``wl.Game()`` to access the properties, e.g.: .. code-block:: lua current_speed = wl.Game().real_Speed .. attribute:: real_speed (RO) The speed that the current game is running at in ms. For example, for game speed = 2x, this returns 2000. .. attribute:: time (RO) The absolute time elapsed since the game was started in milliseconds. .. attribute:: desired_speed (RW) Sets the desired speed of the game in ms per real second, so a speed of 2000 means the game runs at 2x speed. Note that this will not work in network games as expected. .. attribute:: allow_saving (RW) Disable or enable saving. When you show off UI features in a tutorial or scenario, you have to disallow saving because UI elements can not be saved and therefore reloading a game saved in the meantime would crash the game. .. attribute:: interactive_player (RO) The player number of the interactive player, or 0 for spectator .. attribute:: last_save_time (RO) The gametime at which the game was last saved. .. attribute:: type (RO) One string out of :const:`"undefined"`, :const:`"singleplayer"`, :const:`"netclient"`, :const:`"nethost"`, :const:`"replay"`, describing the type of game that is played. .. attribute:: win_condition (RO) The (unlocalized) name of the game's win condition, e.g. :const:`"Endless Game"`. For scenarios this is :const:`"Scenario"`. .. attribute:: scenario_difficulty (RO) The difficulty level of the current scenario. Values range from 1 to the number of levels specified in the campaign's configuration in campaigns.lua. By convention higher values mean more difficult. Throws an error if used outside of a scenario. .. attribute:: allow_diplomacy .. versionadded:: 1.1 (RW) Whether players are allowed to change teams and resign. .. method:: launch_coroutine(func[, when = now]) Hands a Lua coroutine object over to widelands for execution. The object must have been created via :func:`coroutine.create`. The coroutine is expected to :func:`coroutine.yield` at regular intervals with the absolute game time on which the function should be awakened again. You should also have a look at :mod:`core.cr`. :arg func: coroutine object to run :type func: :class:`thread` :arg when: absolute time when this coroutine should run :type when: :class:`integer` :returns: :const:`nil` .. method:: save(name) Requests a savegame. Note that the actual save will be performed later, and that you have no control over any error that may happen by then currently. :arg name: name of save game, as if entered in the save dialog. If this game already exists, it will be silently overwritten. If empty, the autosave name will be used. :type name: :class:`string` :returns: :const:`nil` Editor ------ .. graphviz:: :alt: Dependency graph for class: Editor graph Editor { bgcolor="transparent" node [shape=box, style=filled, fillcolor=white, fontsize=12, fontname="Helvetica"] edge [color=gray] Editor [fillcolor="#118811", fontcolor=white, fontsize=13, shape=oval] EditorGameBase [shape=house, href="../autogen_wl_bases/index.html#editorgamebase", target="_parent"] EditorGameBase -- Editor } .. class:: Editor Child of: :class:`wl.bases.EditorGameBase` The Editor object; it is the correspondence of the :class:`wl.Game` that is used in a Game. Use ``ẁl.Editor()`` to access the properties. World and Tribe Descriptions ---------------------------- .. class:: Descriptions This offers access to the objects in the Widelands world and allows to add new objects. On how to build the world and adding new objects to it, see :ref:`toc_lua_world` and :ref:`lua_tribes`. .. attribute:: tribes_descriptions Returns a list of all the tribes that are available. (RO) a list of :class:`~wl.map.TribeDescription` objects .. attribute:: immovable_descriptions Returns a list of all the immovables that are available. (RO) a list of :class:`~wl.map.ImmovableDescription` objects .. attribute:: terrain_descriptions Returns a list of all the terrains that are available. (RO) a list of :class:`~wl.map.TerrainDescription` objects .. attribute:: worker_descriptions Returns a list of all the workers that are available. (RO) a list of :class:`~wl.map.WorkerDescription` objects .. method:: modify_unit(type, name, property … , value …) This powerful function can be used to modify almost every property of every object description. Currently, support is implemented only for a limited number of properties. Contact the Widelands Development Team if you need access to a property that can not be modified by this function yet. This function is meant to be used **only** by add-ons of the ``tribes`` and ``world`` categories from their ``postload.lua``. **Do not** use it in scenario scripts, add-ons of other types, or the debug console. :arg string type: The object type to modify. See below for a list of valid values. :arg string name: The name of the item to modify. :arg string property…: The property to modify. A property is specified as a sequence of one or more strings. See below for a list of all supported property descriptors. :arg value…: The values for the property. The number and types of the expected values depend on the property being modified (see below). Supported types and properties are: - Resource_ - Terrain_ - Worker_ - Building_ - Productionsite_ - Trainingsite_ - Militarysite_ - Warehouse_ - Tribe_ .. table:: ``"resource"`` :name: resource :width: 100% :widths: 40,50,10 :align: left ============================================ ======================================= ============= Property descriptor Values Since version ============================================ ======================================= ============= :const:`"max_amount"` **amount** (*int*) 1.0 ============================================ ======================================= ============= .. table:: ``"terrain"`` :name: terrain :width: 100% :widths: 40,50,10 :align: left ============================================ ======================================= ============= Property descriptor Values Since version ============================================ ======================================= ============= :const:`"enhancement"` **terrain_name** (*string*) 1.0 :const:`"textures"` **textures_and_fps** (*table*) 1.1 ============================================ ======================================= ============= .. table:: ``"worker"`` :name: worker :width: 100% :widths: 40,50,10 :align: left ============================================ ======================================= ============= Property descriptor Values Since version ============================================ ======================================= ============= :const:`"experience"` **experience** (*int*) 1.0 :const:`"becomes"` **worker_name** (*string*) 1.0 :const:`"programs"`, :const:`"set"` **program_name** (*string*), 1.0 **actions_table** (*table*) ============================================ ======================================= ============= .. table:: ``"building"`` :name: building :width: 100% :widths: 40,50,10 :align: left ============================================================== ======================================= ============= Property descriptor Values Since version ============================================================== ======================================= ============= :const:`"enhancement"` **building_name** (*string*) 1.1 :const:`"buildcost"`, :const:`"remove"` **ware_name** (*string*) 1.1 :const:`"buildcost"`, :const:`"set"` **ware_name** (*string*), 1.1 **amount** (*int*) :const:`"return_on_dismantle"`, :const:`"remove"` **ware_name** (*string*) 1.1 :const:`"return_on_dismantle"`, :const:`"set"` **ware_name** (*string*), 1.1 **amount** (*int*) :const:`"enhancement_cost"`, :const:`"remove"` **ware_name** (*string*) 1.1 :const:`"enhancement_cost"`, :const:`"set"` **ware_name** (*string*), 1.1 **amount** (*int*) :const:`"enhancement_return_on_dismantle"`, :const:`"remove"` **ware_name** (*string*) 1.1 :const:`"enhancement_return_on_dismantle"`, :const:`"set"` **ware_name** (*string*), 1.1 **amount** (*int*) ============================================================== ======================================= ============= .. table:: ``"productionsite"`` :name: productionsite :width: 100% :widths: 40,50,10 :align: left ============================================ ======================================= ============= Property descriptor Values Since version ============================================ ======================================= ============= :const:`"input"`, :const:`"add_ware"` **ware_name** (*string*), 1.0 **amount** (*int*) :const:`"input"`, :const:`"modify_ware"` **ware_name** (*string*), 1.0 **new_amount** (*int*) :const:`"input"`, :const:`"remove_ware"` **ware_name** (*string*) 1.0 :const:`"input"`, :const:`"add_worker"` **worker_name** (*string*), 1.0 **amount** (*int*) :const:`"input"`, :const:`"modify_worker"` **worker_name** (*string*), 1.0 **new_amount** (*int*) :const:`"input"`, :const:`"remove_worker"` **worker_name** (*string*) 1.0 :const:`"programs"`, :const:`"set"` **program_name** (*string*), 1.0 **program_table** (*table*) ============================================ ======================================= ============= .. table:: ``"trainingsite"`` :name: trainingsite :width: 100% :widths: 40,50,10 :align: left ============================================ ======================================= ============= Property descriptor Values Since version ============================================ ======================================= ============= :const:`"soldier_capacity"` **capacity** (*int*) 1.1 :const:`"trainer_patience"` **patience** (*int*) 1.1 ============================================ ======================================= ============= .. table:: ``"militarysite"`` :name: militarysite :width: 100% :widths: 40,50,10 :align: left ============================================ ======================================= ============= Property descriptor Values Since version ============================================ ======================================= ============= :const:`"conquers"` **radius** (*int*) 1.1 :const:`"heal_per_second"` **amount** (*int*) 1.1 :const:`"max_soldiers"` **amount** (*int*) 1.1 ============================================ ======================================= ============= .. table:: ``"warehouse"`` :name: warehouse :width: 100% :widths: 40,50,10 :align: left ============================================ ======================================= ============= Property descriptor Values Since version ============================================ ======================================= ============= :const:`"heal_per_second"` **amount** (*int*) 1.1 :const:`"conquers"` **radius** (*int*) 1.1 ============================================ ======================================= ============= .. table:: ``"tribe"`` :name: tribe :width: 100% :widths: 40,50,10 :align: left ============================================ ======================================= ============= Property descriptor Values Since version ============================================ ======================================= ============= :const:`"add_ware"` **ware_name** (*string*), 1.0 **menu_column** (*int*), **target_quantity** (*int* or *nil*), **preciousness** (*int*), **helptexts** (*table*) :const:`"add_worker"` **worker_name** (*string*), 1.0 **menu_column** (*int*), **target_quantity** (*int* or *nil*), **preciousness** (*int* or *nil*), **helptexts** (*table*) :const:`"add_building"` **building_name** (*string*), 1.0 **helptexts** (*table*) :const:`"add_immovable"` **immovable_name** (*string*), 1.0 **helptexts** (*table*) ============================================ ======================================= ============= Example to add a new worker to an existing tribe; the worker will be appended to the 2nd column in the workers displays (stock menu, warehouse window, economy options), and have no target quantity or preciousness: .. code-block:: lua wl.Descriptions():modify_unit("tribe", "frisians", "add_worker", "frisians_salter", 2, nil, nil, { helptexts = { purpose = _("The salter washes salt from the shores of the sea.") }}) Example to add a new input ware to a building and ensure that the programs use it: .. code-block:: lua -- Add the input wl.Descriptions():modify_unit("productionsite", "frisians_smokery", "input", "add_ware", "salt", 6) -- Overwrite the two predefined programs with new ones wl.Descriptions():modify_unit("productionsite", "frisians_smokery", "programs", "set", "smoke_fish", { descname = _("smoking fish"), actions = { "return=skipped unless economy needs smoked_fish", "consume=fish:2 salt log", "sleep=duration:16s", "animate=working duration:30s", "produce=smoked_fish:2" }}) wl.Descriptions():modify_unit("productionsite", "frisians_smokery", "programs", "set", "smoke_meat", { descname = _("smoking meat"), actions = { "return=skipped when site has fish:2 and economy needs smoked_fish", "return=skipped unless economy needs smoked_meat", "consume=meat:2 salt log", "sleep=duration:16s", "animate=working duration:30s", "produce=smoked_meat:2" }}) -- The main program needs to be overwritten as well – otherwise -- the new program definitions will not not applied! wl.Descriptions():modify_unit("productionsite", "frisians_smokery", "programs", "set", "main", { descname = _("working"), actions = { "call=smoke_fish", "call=smoke_meat" }})