LuaAPI/types/side

From The Battle for Wesnoth Wiki
< LuaAPI‎ | types
Revision as of 02:03, 17 October 2020 by Celtic Minstrel (talk | contribs) (Document the side userdata)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

This represents a side in the current scenario. Its metatable is the wesnoth.sides module, meaning functions of that module can be called on it using colon syntax.

Side identity

  • side.sidenumber

The index of the side. This is the same value used to look up the side in wesnoth.sides.

  • side.side_nametranslatable string

The display name for the side, to be shown in the UI.

  • side.save_idstring

The ID used to track this side's recall list.

  • side.flagimage string
  • side.flag_iconimage string

The images used for the side's flag. Note that if the side doesn't explicitly set a flag, this will return the default flag.

  • side.colorstring

The side's team color.

  • side.user_team_nametranslatable string
  • side.team_namestring

The side's team settings.

Side controller

  • side.controllercontroller type

How the side is controlled. This does not distinguish between local and remote sides, so it is safe to read or write this in multiplayer games.

  • side.is_localboolean

Whether the side is a local side. Careless use will result in out-of-sync errors.

The normal use for it is if you need to show a dialog on the screen that should only pop up for the local player, or that should have a different appearance or behaviour for a non-local player.

Side resources

  • side.goldnumber

The side's current gold amount.

  • side.village_goldnumber
  • side.village_supportnumber
  • side.recall_costnumber
  • side.base_incomenumber

Various settings that influence the side's income.

  • side.num_villagesnumber
  • side.num_unitsnumber
  • side.total_upkeepnumber
  • side.expensesnumber
  • side.net_incomenumber
  • side.total_incomenumber

Various derived values that influence the side's income.

  • side.carryover_bonusnumber
  • side.carryover_percentagenumber
  • side.carryover_addboolean

The side's gold carryover settings.

Misc side settings

  • side.fogboolean
  • side.shroudboolean

Whether the side uses fog and shroud.

  • side.share_visionvision type

The side's policy for sharing vision with allies. This is a string which can be set to one of all (meaning both fog and shroud are shared), shroud (meaning shroud is shared but fog is not), or none (meaning no vision is shared).

  • side.hiddenboolean

Whether the side should be hidden UIs that list sides.

  • side.scroll_to_leaderboolean

Whether the game should scroll to this side's leader when their turn begins.

  • side.suppress_end_turn_confirmationboolean

Whether the game should confirm that the user really meant to end their turn if no units have moved.

  • side.persistentboolean

Whether the side's recall list should be serialized to the saved game so that it can reappear in a later scenario.

  • side.defeat_conditionstring

The side's condition for defeat. For possible values, see the description at SideWML. More information is available here.

  • side.starting_locationlocation

The side's starting location. This is an array table with the x and y coordinates.

  • side.recruitlist of unit type IDs

The side's recruit list.

Multiplayer settings

  • side.factionstring
  • side.faction_nametranslatable string

The name and ID of the side's chosen faction.

  • side.chose_randomboolean

Indicates whether the player explicitly chose their faction or if it was chosen for them at random by the engine.

  • side.lostboolean

If true, this side will be removed from the persistent list at the end of the scenario. This key can also be used to stop the engine from removing a side, by setting it to false. Writing this key only works in a victory/defeat event.

Other side attributes

  • side.variables[path] ↔ variable value
  • side.variables.__cfgall side variables

This is a variables table with the same semantics as wml.variables. If arrays are needed, it (or the side it belongs to) can be passed as the second parameter to wml.array_access.get or wml.array_access.set.

  • side.__cfgconfig

All the side's data as raw WML. This can be used to access values that aren't directly supported.