cw.attributes class

Defines the cw.attributes library, which reads and changes the attribute values, progress and boosts of players.

On the server it updates, progresses and boosts a player's attributes and networks the changes. On the client it keeps the local player's values up to date from the AttrUpdate, AttributeProgress, AttrBoost, AttrBoostClear and AttrClear messages.

Summary

Methods

Boost(player, identifier, attribute, amount, duration)server
Adds or removes a temporary or permanent boost to a player's attribute.
ClearBoosts(player)server
Removes every attribute boost from a player and tells the client.
Fraction(player, attribute, fraction, negative)shared
Returns a player's attribute scaled to a range, so that the maximum value maps to fraction.
Get(player, attribute, boostless, negative)shared
Returns the value and progress of a player's attribute.
GetPanel()client
Returns the attributes menu panel, if one has been created.
IsBoostActive(player, identifier, attribute, amount, duration)server
Returns whether a player has a specific attribute boost.
Progress(player, attribute, amount, gradual)server
Adds progress towards the next point of a player's attribute.
Update(player, attribute, amount)server
Changes a player's attribute by a number of points.

Methods

cw.attributes:Boost(player, identifier, attribute, amount, duration)

server gamemodes/catwork/gamemode/core/libraries/sh_attributes.lua:218

Adds or removes a temporary or permanent boost to a player's attribute.

With an amount, the boost is added (replacing a boost with the same identifier) and sent to the client. Without one, the boost named by identifier is removed, or every boost of the attribute when identifier is also nil. With a nil attribute and no amount, the boost named by identifier is removed from every attribute, or all of the player's boosts are cleared when identifier is nil too. Does nothing for an attribute that cannot be found, or for invalid or uninitialized players.

local id = cw.attributes:Boost(player, 'drunk', ATB_STRENGTH, -10, 120)
cw.attributes:Boost(player, id, ATB_STRENGTH)

Parameters

  • player Player The player to boost
  • identifier String Boost identifier; a unique one is generated when nil and amount is given
  • attribute Any Attribute index, unique ID or name
  • amount Number optional, defaults to nil Points to add while the boost lasts, or nil to remove boosts
  • duration Number optional, defaults to nil How long the boost lasts in seconds, or nil for no time limit

Returns

  • String The boost identifier when a boost was added, true when boosts were removed, or nil when nothing was done

See also

cw.attributes:ClearBoosts(player)

server gamemodes/catwork/gamemode/core/libraries/sh_attributes.lua:152

Removes every attribute boost from a player and tells the client.

Parameters

  • player Player The player to clear

cw.attributes:Fraction(player, attribute, fraction, negative)

shared gamemodes/catwork/gamemode/core/libraries/sh_attributes.lua:312

On the server

Returns a player's attribute scaled to a range, so that the maximum value maps to fraction.

Boosts are included. Results are cached per attribute value.

Parameters

  • player Player The player to check
  • attribute Any Attribute index, unique ID or name
  • fraction Number Value the attribute's maximum maps to
  • negative Any optional, defaults to nil When truthy, negative attribute values are allowed; when a Number, it is used instead of fraction for negative values

Returns

  • Number The scaled value; 0 for invalid or uninitialized players, nil if the attribute cannot be found

On the client

Returns the local player's attribute scaled to a range, so that the maximum value maps to fraction.

This is the client version of the server's cw.attributes:Fraction, without the player argument. Boosts are included and results are cached per attribute value.

Parameters

  • attribute Any Attribute index, unique ID or name
  • fraction Number Value the attribute's maximum maps to
  • negative Any optional, defaults to nil When truthy, negative attribute values are allowed; when a Number, it is used instead of fraction for negative values

Returns

  • Number The scaled value, or nil if the attribute cannot be found

Defined in

cw.attributes:Get(player, attribute, boostless, negative)

shared gamemodes/catwork/gamemode/core/libraries/sh_attributes.lua:345

On the server

Returns the value and progress of a player's attribute.

Boosts are added unless boostless is set, and the total is clamped to the attribute's range and rounded up. Returns nothing for invalid or uninitialized players, unknown attributes, attributes the player has no access to (see cw.core:HasObjectAccess), and with boostless when the player has never had the attribute.

Parameters

  • player Player The player to check
  • attribute Any Attribute index, unique ID or name
  • boostless Boolean optional, defaults to nil Return the raw value without boosts
  • negative Boolean optional, defaults to nil Allow the total to drop below 0, down to minus the maximum

Returns

  • Number The attribute value
  • Number The progress towards the next point (0 to 100)

On the client

Returns the value and progress of the local player's attribute.

This is the client version of the server's cw.attributes:Get, without the player argument, reading the values the server has networked. Boosts are added unless boostless is set, and the total is clamped to the attribute's range and rounded up. Returns nothing for unknown attributes, attributes the player has no access to, and with boostless when the player does not have the attribute.

Parameters

  • attribute Any Attribute index, unique ID or name
  • boostless Boolean optional, defaults to nil Return the raw value without boosts
  • negative Boolean optional, defaults to nil Allow the total to drop below 0, down to minus the maximum

Returns

  • Number The attribute value
  • Number The progress towards the next point (0 to 100)

Defined in

cw.attributes:GetPanel()

client gamemodes/catwork/gamemode/core/libraries/sh_attributes.lua:395

Returns the attributes menu panel, if one has been created.

Returns

  • Panel The attributes panel, or nil

cw.attributes:IsBoostActive(player, identifier, attribute, amount, duration)

server gamemodes/catwork/gamemode/core/libraries/sh_attributes.lua:169

Returns whether a player has a specific attribute boost.

When amount or duration is given, the boost must also match it.

Parameters

  • player Player The player to check
  • identifier String Boost identifier, as returned by cw.attributes:Boost
  • attribute Any Attribute index, unique ID or name
  • amount Number optional, defaults to nil Amount the boost must have
  • duration Number optional, defaults to nil Duration the boost must have, in seconds

Returns

  • Boolean Whether the boost is active, or nil if the player or attribute has no such boost

cw.attributes:Progress(player, attribute, amount, gradual)

server gamemodes/catwork/gamemode/core/libraries/sh_attributes.lua:26

Adds progress towards the next point of a player's attribute.

Progress runs from 0 to 100. Reaching 100 raises the attribute by one point with Player:UpdateAttribute and carries the remainder over; dropping below 0 lowers it by one point, or leaves it at no progress when the attribute has no points to lose. With gradual, positive progress shrinks as the attribute nears its maximum. Runs the OnAttributeProgress hook (via hook.Run) before applying the progress; a number it returns replaces the amount.

Parameters

  • player Player The player whose attribute progresses
  • attribute Any Attribute index, unique ID or name, as accepted by cw.attribute:FindByID
  • amount Number Progress to add; negative values remove progress
  • gradual Boolean optional, defaults to nil Whether to scale positive progress down as the attribute grows

Returns

  • Boolean false when the attribute is invalid or already at its maximum
  • String The reason, as a language phrase

See also

cw.attributes:Update(player, attribute, amount)

server gamemodes/catwork/gamemode/core/libraries/sh_attributes.lua:106

Changes a player's attribute by a number of points.

The result is clamped between 0 and the attribute's maximum. Raising the attribute resets its progress. The new value is sent to the player and the PlayerAttributeUpdated hook is run (via hook.Run) with the player, the attribute table and amount.

Parameters

  • player Player The player whose attribute changes
  • attribute Any Attribute index, unique ID or name, as accepted by cw.attribute:FindByID
  • amount Number optional, defaults to nil Points to add; negative values remove points, nil adds none

Returns

  • Boolean Whether the attribute was updated
  • String The reason it was not, as a language phrase

See also

Defined in