: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 set to run at in ms. For example, for game speed = 2x, this returns 2000. In network games this is the speed resulting from the votes of the players, so it can be different from the local player's :attr:`desired_speed`. Else it is the same as :attr:`desired_speed`. .. 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 in network games this is the speed voted by the current player. The speed resulting from the votes is in :attr:`real_speed`. .. 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 value of :attr:`wl.game.Player.number` of the interactive player .. 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:: win_condition_duration .. versionadded:: 1.2 (RO) The time limit configured for the game's win condition, in minutes. Only valid if the selected win condition allows configuring the time limit. .. 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. .. attribute:: allow_naval_warfare .. versionadded:: 1.2 (RW) Whether players are allowed to refit ships to warships and launch coastal invasions and ship-to-ship battles. .. 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:: building_descriptions .. versionadded:: 1.2 (RO) An :class:`array` of all :class:`~wl.map.BuildingDescription` objects that are available. .. 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*) :const:`"buildcost"`, :const:`"set"` **ware_name** (*string*), 1.2 **amount** (*int*) :const:`"buildcost"`, :const:`"remove"` **ware_name** (*string*), 1.2 ============================================ ======================================= ============= .. 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 :const:`"max_garrison"` **amount** (*int*) 1.2 ============================================ ======================================= ============= .. 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" }})