[Lib] Trait

Overview

This lib allows for adding a custom trait to a unit both in the UI and as an icon on the board. If you only need the UI icon/description, consider using Trait Replace Lib. This was originally created by Lemonymous here and then I updated it to support multiple icons and cycling between them.

Any issues or concerns? Join the Redacted Rice Discord and @Das Keifer

Multiple Traits and Cycling

When multiple traits apply to the same pawn, the library handles them intelligently:

Icon Cycling: Board icons (specified via icon_glow) will automatically cycle every 1.25 seconds. If a trait has no icon_glow, it will only appear in the tooltip and won't cycle on the board.

Tooltip Descriptions: When hovering over a unit with multiple active traits, all trait descriptions are combined and shown in a single tooltip with the heading "Modded Traits".

Priority Order: When multiple traits match a pawn, they are evaluated in this priority:

1. func traits (highest priority)
2. pilotSkill traits
3. pawnType traits (lowest priority)

Within each category, traits are ordered by creation order (first created has highest priority).

API

• trait
  • add
  • update

 

trait

A library providing functionality for adding traits to pawns. Traits are purely visual - displaying an icon and a description. When multiple traits apply to a unit, their icons will cycle every 1.25 seconds, and their descriptions will be combined in the tooltip.

 

add

Argument name	Type	Description
trait	table	A table with fields describing the trait being added

The trait object, passed as first argument, can have the following fields:

Field	Type	Description
pawnType	string	(optional*) The pawn type to apply the trait to
pilotSkill	string	(optional*) The pilot skill to associated with this trait
func	function	(optional*) Function describing when to apply the trait to a unit
icon	string	(optional) Path to icon for pilot tooltip - relative to mod, or path to asset in resource.dat - defaults to no icon
icon_glow	string	(optional) Path to icon shown on the game board - relative to mod, or path to asset in resource.dat - defaults to no icon. If not provided, trait won't be displayed on board but will still show in tooltips
icon_offset	Point	(optional) Offset for icon when displayed on unit - defaults to no offset
desc_title	string	Displayed description title for trait
desc_text	string	Displayed description text for trait
desc	table	(optional) Alternative way to specify description as {title, text} or {title = "...", text = "..."}. If provided, overrides desc_title and desc_text

 

Adds a trait that will be automatically be updated every time a pawn changes position.

Note*: Exactly one of func, pilotSkill and pawnType must be specified. If func is specified, pilotSkill and pawnType will be ignored. Likewise, if pilotSkill is specified, pawnType will be ignored.

If func is specified, the trait will be applied to a pawn if the function provided returns true for a pawn. The function will be called any time a pawn changes position, or if the function update is manually called. func has the following signature: func(trait, pawn, loc) where trait is the trait table of the trait being analyzed, pawn is the pawn being checked and loc is the tile to check (which may be different from pawn:GetSpace() in the case of previewing a move).

If pilotSkill is specified, the trait will be applied to any pawn that has a pilot with this pilot skill.

If pawnType is specified, the trait will be applied to any pawn of this type.

Example:

-- Add a trait for all Mechs
trait:add({
    pawnType = "TechnoVek_Mech",
    icon = "img/combat/icons/icon_shield.png",
    icon_glow = "img/combat/icons/icon_shield_glow.png",
    desc_title = "Shielded",
    desc_text = "This mech has a shield"
})

-- Add a conditional trait that takes priority
trait:add({
    func = function(trait, pawn, loc)
        return pawn:GetHealth() <= 1
    end,
    icon_glow = "img/combat/icons/icon_warning_glow.png",
    desc_title = "Critical Damage",
    desc_text = "This unit is nearly destroyed!"
})

 

update

Argument name	Type	Description
loc	Point	Point on board to update

Manually updates the displayed trait on a tile. Useful for traits that can change without pawns changing position.