merchant

Represents an NPC which the crew (or others) can trade with.

Vars
HIGH_DISPOSITION_THRESHOLD	Disposition values at or above this value are considered to be 'high' for certain purposes.
MAX_DISPOSITION_THRESHOLD	Disposition values above this value cease to have any additional effect for certain purposes.
TRANSACTION_BUYING	Indicates a transaction where the merchant is buying from players.
TRANSACTION_SELLING	Indicates a transaction where the merchant is selling to players.
accepts_goods_as_payment	Whether or not the merchant accepts items as payment. This must be TRUE for barter to be possible.
accepts_money_as_payment	Whether or not the merchant accepts money as payment.
active_demand	List of commodities that the merchant wants to buy from players.
active_supply	List of commodities that are presently being offered for sale.
bribe_disposition_divisor	Determines how much disposition goes up when bribed, by dividing the bribe amount by this value.
bribe_duration_divisor	Determines how much longer, in minutes, merchants will stay when bribed (if they are temporary), by dividing the bribe amount by this value.
comms_refusal_threshold	Merchants will refuse to interact with anyone who has this amount of disposition, or lower.
currency_used	The currency used by the merchant. If unset, the map's default currency is used instead.
current_cash	How much cash the merchant currently has. If set to null, the merchant has unlimited funds.
demand_potential	List containing one or more `/decl/merchant_potential_commodities`, which are used to determine what the merchant wants to buy from players.
demand_strategy	Determines how demand is initially stocked and how it rotates over time, if at all.
duration_of_stay	How long the merchant is planning to stay, in minutes. Set automatically on init if `is_temporary_merchant` is true.
forbidden_objects	List of type paths the merchant refuses to buy, with a unique dialogue compared to regular junk.
haggle_disposition_penalty	Scales how far disposition drops when players try to offer bad deals to this merchant. Higher numbers make the merchants get fed up faster.
haggling_refusal_threshold	Determines how far away from the merchant's perferred price players can haggle for. The actual threshold is randomized to be between 0 and this value.
hub	The trade hub which this merchant is located at.
inactive_demand	List of commodities that didn't make the cut for `active_demand`.
inactive_supply	List of commodities that didn't make the cut for `active_supply`.
is_temporary_merchant	If true, the merchant will eventually leave their hub, and players won't be able to interact with them anymore. This can be changed in-round to make temp. merchants stay.
merchant_languages	List of languages which the merchant communicates with. Players who do not possess at least one of these cannot easily interact with the merchant, and the text will be scrambled in the UI.
name	The merchant's name, shown in the UI to players. If blank, a random name will be generated.
name_background	Background decl which will generate a random name for the merchant, overwriting it, if it is set.
negative_disposition_multiplier	Multiplies how easy it is to lower disposition with this merchant.
origin	Where the merchant is trading from, or in other words, the store's name. Shown in the UI.
positive_disposition_multiplier	Multiplies how easy it is to raise disposition with this merchant.
possible_origins	If set, `origin` is replaced by one of these randomly at init.
price_variance	Object values can randomly vary based on this. Values higher than 1.0 make potential prices 'swingier'. A value of 1.0 causes prices to be consistent.
refuse_anonymous_comms	If true, the merchant won't respond to hails if the user lacks an ID.
refuse_bribes	If TRUE, the merchant cannot be bribed with cash under any circumstances.
refuse_gifts	If TRUE, the merchant will not accept receiving wanted items for free.
refuse_haggling	If TRUE, the merchant refuses all attempts to haggle buying or selling prices.
remembered_identities	List of character names (on their IDs) the merchant remembers from prior interactions, along with their individual disposition values.
skill_level	How good the merchant is at trading, and is compared against players' Finance skills to determine whether the merchant or player has an advantage in negotiations.
speech	Decl which contains dialogue shown to players interacting with this merchant.
starting_cash_lower_bound	Upper bound for how much cash a merchant can start with.
starting_cash_upper_bound	Lower bound for how much cash a merchant can start with.
supply_potential	List containing one or more `/decl/merchant_potential_commodities`, which are used to determine what the merchant could sell to players.
supply_strategy	Determines how supply is initially stocked and how it rotates over time, if at all.
times_complimented	How many times this merchant received a compliment. Used to punish compliment spam.
typical_duration_lower_bound	Lower bound for how long this merchant stays, in minutes.
typical_duration_upper_bound	Upper bound for how long this merchant stays, in minutes.
will_pay_with_money	If false, the merchant cannot give money for items, and players must barter to trade with them.
Procs
adjust_cash	Adds or subtracts a specific quantity from the merchant's cash reserves.
adjust_dispositon	Increases or decreases the merchant's opinion of a mob's associated identity by a set amount. Due to disposition multipliers, the actual result may be different or may not actually change anything. Returns the actual change in disposition.
bribe	Attempts to bribe the merchant with `amount` units of value, which will generally increase their disposition and make them stay longer, if applicable. Override for extra behavior when bribed.
calculate_haggle_limit	Returns the 'price' of an item that the merchant will still accept, even if it's slightly off from their regular price.
can_be_understood	Determines if the user can understand what this merchant says. Users who cannot understand merchants will be greatly hindered in interacting with them.
can_bribe	Determines if the merchant is bribable.
can_hail	Determines if the merchant will refuse hails or not. Override for custom hailing rules. Despite the name, interaction will cease if this returns FALSE in the middle of interacting with a merchant, not just the beginning.
compliment	Attempts to raise the merchant's disposition with flattery. Note that this returns TRUE even if no disposition is gained, but merely that the merchant took it well.
default_disposition	Determines the default disposition value for a new identity. This can be overriden to conditionally have merchants have different starting disposition values. One example could be to simulate certain merchants already having a vague opinion on certain kinds of characters, perhaps by pulling from a character's background details.
denying_anonymous_comms	Returns TRUE if the merchant doesn't want to interact with scary nameless people.
evaluate_offer	Returns TRUE if the merchant would agree to an offer to buy or sell at the inputted price.
find_demand_commodity	Returns a commodity instance representing an item in demand, that matches the inputted item instance, if one exists.
find_supply_commodity	Returns a commodity instance representing an item being sold, that matches the inputted item instance or type path, if one exists.
generate_inventory	Creates commodity datums out of `/decl/merchant_potential_commodity` types inside of the relevant `[supply\|demand]_potential` lists.
get_disposition	Retrieves the disposition value for a particular mob instance with an associated 'identity', which is just their name as stated on their ID, if one exists. Merchants will treat mobs with the same identity as being the same person for opinion purposes. This will likely be most common in the case of people without IDs being remembered as 'Unknown'.
get_identity	Retrieves a string to be used as a particular mob's 'identity'. Generally it will just be what their ID says, or Unknown if they lack one, as presumably the trading computer reads it off the ID. Using name strings instead of weakrefs to actual mobs opens the door to impersonation as well as letting players have a second chance if they accidentally offended the merchant, by showing up as "Unknown" (assuming nobody else burned that identity as well).
get_item_value	Returns how much the merchant values a particular item.
get_value_of_items	Returns how much the merchant values a group of items, provided for convenience.
hail	Determines if hailing the merchant succeeded or not.
has_cash	Returns whether the merchant has a specific quantity of cash.
insult	Deliberately worsens the relationship between the merchant and a mob's associated identity, for whatever reason.
offer_contains_forbidden_items	Returns TRUE if one or more items in the list are inside of the merchant's list of forbidden types.
offer_contains_wanted_items	Returns TRUE if all items in the list are in demand by the merchant.
on_completed_transaction	Called after a successful trade, either buying or selling something. Bribes are not considered transactions for that purpose. Override for custom behavior.
on_disposition_changed	Called whenever the merchant's disposition changes. Override for custom behavior when that happens.
pre_hail	Called just before the hail actually happens.
pre_inventory_generation	Called just before merchant inventory is built. This exists mostly for cross-modpack interactions to inject their items into a particular merchant type.
process	Called by the trade hub once a minute.
remember_identity	Commits a newly encountered identity to the merchant's memory, giving it a default opinion value. Called automatically if the merchant fails to pull an already existing identity from `remembered_identities`.
scramble_response	Garbles the text based on the merchant's languages. Generally you want to check and then scramble just before serving the text to each player, so that different players will see what they're supposed to see.
set_disposition	Sets the merchant's opinion of a mob's associated identity to a specific value, no matter what.
setup_inventory	Determines which items are put into active and inactive 'supply' and 'demand' lists, based on the merchant's `[supply\|demand]_strategy` decls.
transaction_disposition_shift	Called after a successful trade, awarding disposition based on how much value the merchant bought or sold.

Var Details

var
HIGH_DISPOSITION_THRESHOLD
– /const

Disposition values at or above this value are considered to be 'high' for certain purposes.

var
MAX_DISPOSITION_THRESHOLD
– /const

Disposition values above this value cease to have any additional effect for certain purposes.

var
TRANSACTION_BUYING
– /const

Indicates a transaction where the merchant is buying from players.

var
TRANSACTION_SELLING
– /const

Indicates a transaction where the merchant is selling to players.

var
accepts_goods_as_payment

Whether or not the merchant accepts items as payment. This must be TRUE for barter to be possible.

var
accepts_money_as_payment

Whether or not the merchant accepts money as payment.

var
active_demand
– /list

List of commodities that the merchant wants to buy from players.

var
active_supply
– /list

List of commodities that are presently being offered for sale.

var
bribe_disposition_divisor

Determines how much disposition goes up when bribed, by dividing the bribe amount by this value.

var
bribe_duration_divisor

Determines how much longer, in minutes, merchants will stay when bribed (if they are temporary), by dividing the bribe amount by this value.

var
comms_refusal_threshold

Merchants will refuse to interact with anyone who has this amount of disposition, or lower.

var
currency_used
– /decl/currency

The currency used by the merchant. If unset, the map's default currency is used instead.

var
current_cash

How much cash the merchant currently has. If set to null, the merchant has unlimited funds.

var
demand_potential
– /list

List containing one or more /decl/merchant_potential_commodities, which are used to determine what the merchant wants to buy from players.

var
demand_strategy
– /decl/merchant_inventory_strategy

Determines how demand is initially stocked and how it rotates over time, if at all.

var
duration_of_stay

How long the merchant is planning to stay, in minutes. Set automatically on init if is_temporary_merchant is true.

var
forbidden_objects
– /list

List of type paths the merchant refuses to buy, with a unique dialogue compared to regular junk.

var
haggle_disposition_penalty

Scales how far disposition drops when players try to offer bad deals to this merchant. Higher numbers make the merchants get fed up faster.

var
haggling_refusal_threshold

Determines how far away from the merchant's perferred price players can haggle for. The actual threshold is randomized to be between 0 and this value.

var
hub
– /datum/trade_hub

The trade hub which this merchant is located at.

var
inactive_demand
– /list

List of commodities that didn't make the cut for active_demand.

var
inactive_supply
– /list

List of commodities that didn't make the cut for active_supply.

var
is_temporary_merchant

If true, the merchant will eventually leave their hub, and players won't be able to interact with them anymore. This can be changed in-round to make temp. merchants stay.

var
merchant_languages
– /list

List of languages which the merchant communicates with. Players who do not possess at least one of these cannot easily interact with the merchant, and the text will be scrambled in the UI.

var
name

The merchant's name, shown in the UI to players. If blank, a random name will be generated.

var
name_background
– /decl/background_detail

Background decl which will generate a random name for the merchant, overwriting it, if it is set.

var
negative_disposition_multiplier

Multiplies how easy it is to lower disposition with this merchant.

var
origin

Where the merchant is trading from, or in other words, the store's name. Shown in the UI.

var
positive_disposition_multiplier

Multiplies how easy it is to raise disposition with this merchant.

var
possible_origins
– /list

If set, origin is replaced by one of these randomly at init.

var
price_variance

Object values can randomly vary based on this. Values higher than 1.0 make potential prices 'swingier'. A value of 1.0 causes prices to be consistent.

var
refuse_anonymous_comms

If true, the merchant won't respond to hails if the user lacks an ID.

var
refuse_bribes

If TRUE, the merchant cannot be bribed with cash under any circumstances.

var
refuse_gifts

If TRUE, the merchant will not accept receiving wanted items for free.

var
refuse_haggling

If TRUE, the merchant refuses all attempts to haggle buying or selling prices.

var
remembered_identities
– /list

List of character names (on their IDs) the merchant remembers from prior interactions, along with their individual disposition values.

var
skill_level

How good the merchant is at trading, and is compared against players' Finance skills to determine whether the merchant or player has an advantage in negotiations.

var
speech
– /decl/merchant_speech

Decl which contains dialogue shown to players interacting with this merchant.

var
starting_cash_lower_bound

Upper bound for how much cash a merchant can start with.

var
starting_cash_upper_bound

Lower bound for how much cash a merchant can start with.

var
supply_potential
– /list

List containing one or more /decl/merchant_potential_commodities, which are used to determine what the merchant could sell to players.

var
supply_strategy
– /decl/merchant_inventory_strategy

Determines how supply is initially stocked and how it rotates over time, if at all.

var
times_complimented

How many times this merchant received a compliment. Used to punish compliment spam.

var
typical_duration_lower_bound

Lower bound for how long this merchant stays, in minutes.

var
typical_duration_upper_bound

Upper bound for how long this merchant stays, in minutes.

var
will_pay_with_money

If false, the merchant cannot give money for items, and players must barter to trade with them.

Proc Details

proc
adjust_cash
(amount)

Adds or subtracts a specific quantity from the merchant's cash reserves.

proc
adjust_dispositon
(amount, /mob/user)

Increases or decreases the merchant's opinion of a mob's associated identity by a set amount. Due to disposition multipliers, the actual result may be different or may not actually change anything. Returns the actual change in disposition.

proc
bribe
(amount, /mob/user)

Attempts to bribe the merchant with amount units of value, which will generally increase their disposition and make them stay longer, if applicable. Override for extra behavior when bribed.

proc
calculate_haggle_limit
(/atom/movable/item, transaction_direction, /mob/user)

Returns the 'price' of an item that the merchant will still accept, even if it's slightly off from their regular price.

atom/movable/item: Instance or typepath of an item that will be evaluated.
transaction_direction: Determines whether the haggling limit is for buying or selling item. This is from the perspective of the merchant.
- TRANSACTION_SELLING: Merchant is selling to the user. Merchant wants a higher price, user presumably wants a lower one.
- TRANSACTION_BUYING: Merchant is buying from the user. Merchant wants a lower price, user presumably wants a higher one.
mob/user: The user who is trying to haggle with the merchant.

proc
can_be_understood
(/mob/user)

Determines if the user can understand what this merchant says. Users who cannot understand merchants will be greatly hindered in interacting with them.

proc
can_bribe
()

Determines if the merchant is bribable.

proc
can_hail
(/mob/user)

Determines if the merchant will refuse hails or not. Override for custom hailing rules. Despite the name, interaction will cease if this returns FALSE in the middle of interacting with a merchant, not just the beginning.

proc
compliment
(/mob/user)

Attempts to raise the merchant's disposition with flattery. Note that this returns TRUE even if no disposition is gained, but merely that the merchant took it well.

proc
default_disposition
(/mob/user)

Determines the default disposition value for a new identity. This can be overriden to conditionally have merchants have different starting disposition values. One example could be to simulate certain merchants already having a vague opinion on certain kinds of characters, perhaps by pulling from a character's background details.

proc
denying_anonymous_comms
(/mob/user)

Returns TRUE if the merchant doesn't want to interact with scary nameless people.

proc
evaluate_offer
(/list/items, user_offer, transaction_direction, /mob/user)

Returns TRUE if the merchant would agree to an offer to buy or sell at the inputted price.

list/items: List containing object instances, or type paths that the user is attempting to sell to, or buy from, the merchant. Used to obtain the merchant's preferred price.
user_offer: The amount of value that the user is offering for items. If the user isn't haggling, this is automatically filled in with what the merchant would've offered and should always succeed.
transaction_direction: Determines whether the merchant is buying or selling to the user. Note that the direction is from the perspective of the merchant.
- TRANSACTION_SELLING: Merchant is selling to the user. Merchant wants a higher price, user presumably wants a lower one.
- TRANSACTION_BUYING: Merchant is buying from the user. Merchant wants a lower price, user presumably wants a higher one.
mob/user: The user who initiated the trade.

proc
find_demand_commodity
(/atom/movable/item)

Returns a commodity instance representing an item in demand, that matches the inputted item instance, if one exists.

atom/movable/item: Instance to find a matching commodity instance for.

proc
find_supply_commodity
(/atom/movable/item)

Returns a commodity instance representing an item being sold, that matches the inputted item instance or type path, if one exists.

atom/movable/item: Instance or type path to find a matching commodity instance for.

proc
generate_inventory
()

Creates commodity datums out of /decl/merchant_potential_commodity types inside of the relevant [supply|demand]_potential lists.

proc
get_disposition
(/mob/user)

Retrieves the disposition value for a particular mob instance with an associated 'identity', which is just their name as stated on their ID, if one exists. Merchants will treat mobs with the same identity as being the same person for opinion purposes. This will likely be most common in the case of people without IDs being remembered as 'Unknown'.

proc
get_identity
(/mob/user)

Retrieves a string to be used as a particular mob's 'identity'. Generally it will just be what their ID says, or Unknown if they lack one, as presumably the trading computer reads it off the ID. Using name strings instead of weakrefs to actual mobs opens the door to impersonation as well as letting players have a second chance if they accidentally offended the merchant, by showing up as "Unknown" (assuming nobody else burned that identity as well).

proc
get_item_value
(/atom/movable/item, transaction_direction, /mob/user)

Returns how much the merchant values a particular item.

atom/movable/item: Instance or typepath of the item to evaluate.
transaction_direction: Determines which price modifiers to use for determining the price of something. Note that the direction is from the perspective of the merchant.
- TRANSACTION_SELLING gives the price of an item the merchant is selling to players.
- TRANSACTION_BUYING gives how much the merchant would buy a particular item from players.
mob/user: The user which initiated the item's evaluation.

proc
get_value_of_items
(/list/items, transaction_direction, /mob/user)

Returns how much the merchant values a group of items, provided for convenience.

list/items: List containing instances or typepaths of items to evaluate.
transaction_direction: Determines which list to use for determining the price of something. Note that the direction is from the perspective of the merchant.
- TRANSACTION_SELLING gives the price of each item in the list the merchant would use to sell to players.
- TRANSACTION_BUYING gives how much the merchant would pay to buy all of the items from players.
mob/user: The user which initiated the calculation.

proc
hail
(/mob/user)

Determines if hailing the merchant succeeded or not.

proc
has_cash
(amount)

Returns whether the merchant has a specific quantity of cash.

proc
insult
(/mob/user)

Deliberately worsens the relationship between the merchant and a mob's associated identity, for whatever reason.

proc
offer_contains_forbidden_items
(/list/items)

Returns TRUE if one or more items in the list are inside of the merchant's list of forbidden types.

proc
offer_contains_wanted_items
(/list/items)

Returns TRUE if all items in the list are in demand by the merchant.

proc
on_completed_transaction
(/mob/user, /list/items, transaction_direction, wanted_value, actual_value, /turf/location)

Called after a successful trade, either buying or selling something. Bribes are not considered transactions for that purpose. Override for custom behavior.

mob/user: The user who initiated the trade.
list/items: The object instances which were traded for. Note that items sold to a merchant are about to be deleted.
transaction_direction: Whether the merchant was buying from, or selling to, the user.
- TRANSACTION_SELLING: The merchant sold the contents of items to user.
- TRANSACTION_BUYING: The merchant bought the contents of items from user.
wanted_value: How much value the merchant wanted for the trade, which might not be equal to actual_value.
actual_value: How much value the merchant received from the trade, either in cash or the worth of items received for if bartering.
turf/location: The turf containing the merchant pad that was used for the transaction. This can be used to derive further location-based information, like the merchant pad's z-level.

proc
on_disposition_changed
(old_disposition, new_disposition, /mob/user)

Called whenever the merchant's disposition changes. Override for custom behavior when that happens.

old_disposition: What the merchant's disposition was prior to whatever changed it.
new_disposition: What the merchant's disposition is currently.
mob/user: The mob who caused a disposition change associated with their identity.

proc
pre_hail
(/mob/user)

Called just before the hail actually happens.

proc
pre_inventory_generation
()

Called just before merchant inventory is built. This exists mostly for cross-modpack interactions to inject their items into a particular merchant type.

proc
process
(tick_count)

Called by the trade hub once a minute.

proc
remember_identity
(/mob/user)

Commits a newly encountered identity to the merchant's memory, giving it a default opinion value. Called automatically if the merchant fails to pull an already existing identity from remembered_identities.

proc
scramble_response
(/mob/user, response_text)

Garbles the text based on the merchant's languages. Generally you want to check and then scramble just before serving the text to each player, so that different players will see what they're supposed to see.

proc
set_disposition
(amount, /mob/user)

Sets the merchant's opinion of a mob's associated identity to a specific value, no matter what.

proc
setup_inventory
()

Determines which items are put into active and inactive 'supply' and 'demand' lists, based on the merchant's [supply|demand]_strategy decls.

proc
transaction_disposition_shift
(/list/items, transaction_direction, /mob/user)

Called after a successful trade, awarding disposition based on how much value the merchant bought or sold.

list/items: Objects which were just bought or sold to the merchant. Note that items sold to a merchant are about to be deleted.
transaction_direction: Whether the merchant was buying from, or selling to, the user.
- TRANSACTION_SELLING: The merchant sold the contents of items to user.
- TRANSACTION_BUYING: The merchant bought the contents of items from user.
mob/user: The user who initiated the trade.

merchant /datum/merchant

Vars

Procs

Var Details

var HIGH_DISPOSITION_THRESHOLD – /const

var MAX_DISPOSITION_THRESHOLD – /const

var TRANSACTION_BUYING – /const

var TRANSACTION_SELLING – /const

var accepts_goods_as_payment

var accepts_money_as_payment

var active_demand – /list

var active_supply – /list

var bribe_disposition_divisor

var bribe_duration_divisor

var comms_refusal_threshold

var currency_used – /decl/currency

var current_cash

var demand_potential – /list

var demand_strategy – /decl/merchant_inventory_strategy

var duration_of_stay

var forbidden_objects – /list

var haggle_disposition_penalty

var haggling_refusal_threshold

var hub – /datum/trade_hub

var inactive_demand – /list

var inactive_supply – /list

var is_temporary_merchant

var merchant_languages – /list

var name

var name_background – /decl/background_detail

var negative_disposition_multiplier

var origin

var positive_disposition_multiplier

var possible_origins – /list

var price_variance

var refuse_anonymous_comms

var refuse_bribes

var refuse_gifts

var refuse_haggling

var remembered_identities – /list

var skill_level

var speech – /decl/merchant_speech

var starting_cash_lower_bound

var starting_cash_upper_bound

var supply_potential – /list

var supply_strategy – /decl/merchant_inventory_strategy

var times_complimented

var typical_duration_lower_bound

var typical_duration_upper_bound

var will_pay_with_money