LuaAPI/types/side

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.side → number

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

• side.side_name ↔ translatable string

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

• side.save_id → string

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

• side.flag ↔ image string
• side.flag_icon ↔ image 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.color ↔ string

The side's team color.

• side.user_team_name ↔ translatable string
• side.team_name ↔ string

The side's team settings.

Side controller

• side.controller ↔ controller 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_local → boolean

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.gold ↔ number

The side's current gold amount.

• side.village_gold ↔ number
• side.village_support ↔ number
• side.recall_cost ↔ number
• side.base_income ↔ number

Various settings that influence the side's income.

• side.num_villages → number
• side.num_units → number
• side.total_upkeep → number
• side.expenses → number
• side.net_income → number
• side.total_income → number

Various derived values that influence the side's income.

• side.carryover_bonus ↔ number
• side.carryover_percentage ↔ number
• side.carryover_add ↔ boolean

The side's gold carryover settings.

Misc side settings

• side.fog ↔ boolean
• side.shroud ↔ boolean

Whether the side uses fog and shroud.

• side.shroud_data ↔ shroud data string

The current shroud for the side, as a shroud data string (see SideWML).

• side.share_vision ↔ vision 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.hidden ↔ boolean

Whether the side should be hidden UIs that list sides.

• side.scroll_to_leader ↔ boolean

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

• side.suppress_end_turn_confirmation ↔ boolean

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

• side.persistent ↔ boolean

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

• side.defeat_condition ↔ string

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

• side.starting_location → location

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

• side.recruit ↔ list of unit type IDs

The side's recruit list.

Multiplayer settings

• side.faction → string
• side.faction_name → translatable string

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

• side.chose_random → boolean

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

• side.lost ↔ boolean

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.__cfg → all 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.__cfg → config

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