dsrc/sku.0/sys.server/compiled/game/script/library/money.scriptlib

/**********************************************************************
 * Copyright (c)2000-2002 Sony Online Entertainment Inc.
 * All Rights Reserved
 *
 * Title:        pclib.scriptlib
 * Description:  base player script library
 * @author       $Author:$
 * @version      $Revision:$
 **********************************************************************/

/***** INCLUDES ********************************************************/

include library.utils;
include library.prose;

/***** CONSTANTS *******************************************************/

//PAY SCRIPTS
const string SCRIPT_PAY_ACTOR			= "money.pay.actor";

const string SCRIPT_ACCT_PAY			= "money.acct_pay.target";

//TEMP (VAR SOLUTION) MONEY OBJVARS
const string VAR_MONEY_BASE             = "money";
const string VAR_MONEY_CASH             = "money.cash";
const string VAR_MONEY_BANK             = "money.bank";

//PAY TRACKING
const string VAR_PAY_TALLY				= "money.pay.tally";

//MONEY TYPES (MT)
const int MT_CASH                          = 0;
const int MT_BANK                          = 1;
const int MT_TOTAL                         = 2;
const int MT_MAX                           = 3;

const string[] MT_NAME                     = {"cash", "bank", "total"};

//MISC HANDLER
const string HANDLER_NONE                           = "noHandler";

//BANKING HANDLER CONSTANTS
const string HANDLER_BANK_SUCCESS                   = "handleBankSuccess";
const string HANDLER_BANK_UNKNOWN_ERROR             = "handleBankUnknownError";

const string HANDLER_BANK_WITHDRAW_ERROR            = "handleBankWithdrawError";
const string HANDLER_BANK_DEPOSIT_ERROR             = "handleBankDepositError";
const string HANDLER_BANK_TRANSFER_ERROR            = "handleBankTransferError";
const string HANDLER_CREDIT_TRANSFER_ERROR          = "handleCreditTransferError";

const string HANDLER_COVERT_SUCCESS                 = "handleCovertTransactionPass";
const string HANDLER_COVERT_ERROR             		= "handleCovertTransactionFail";

const string HANDLER_PAYMENT_REQUEST           		= "handlePaymentRequest";

const string HANDLER_PAY_DEPOSIT               		= "handlePayDeposit";

const string HANDLER_PAY_PASS                 		= "handlePayPass";
const string HANDLER_PAY_FAIL             			= "handlePayFail";

//SUI STRING/STRING_ID CONSTANTS
const string MSG_BANK_SUCCESS                       = "@base_player:bank_success";
const string MSG_BANK_ERROR                         = "@error_message:bank_error";

const string MSG_BANK_WITHDRAW_ERROR                = "@error_message:bank_withdraw";
const string MSG_BANK_DEPOSIT_ERROR                 = "@error_message:bank_deposit";
const string MSG_BANK_TRANSFER_ERROR                = "@error_message:bank_transfer";
const string MSG_CASH_TRANSFER_ERROR                = "@error_message:cash_transfer";

const string_id SID_BANK_SUCCESS                    = new string_id("base_player","bank_success");
const string_id SID_BANK_ERROR                      = new string_id("error_message","bank_error");

const string_id SID_BANK_WITHDRAW_ERROR             = new string_id("error_message","bank_withdraw");
const string_id SID_BANK_DEPOSIT_ERROR              = new string_id("error_message","bank_deposit");
const string_id SID_BANK_TRANSFER_ERROR             = new string_id("error_message","bank_transfer");
const string_id SID_CASH_TRANSFER_ERROR             = new string_id("error_message","cash_transfer");

const string_id SID_NULL_TRANSACTION_ERROR			= new string_id("error_message","bank_null_transaction");

const string_id PROSE_PAY_NSF						= new string_id("error_message","prose_pay_nsf");
const string_id PROSE_PAY_FAIL						= new string_id("error_message","prose_pay_fail");

const string_id PROSE_PAY_ACCT_FAIL					= new string_id("error_message","prose_pay_fail");

const string_id PROSE_PAY_SUCCESS					= new string_id("base_player","prose_pay_success");
const string_id PROSE_PAY_SUCCESS_NO_TARGET			= new string_id("base_player","prose_pay_success_no_target");

const string_id PROSE_PAY_ACCT_SUCCESS				= new string_id("base_player","prose_pay_acct_success");

const string_id PROSE_DEPOSIT_SUCCESS				= new string_id("base_player","prose_deposit_success");
const string_id PROSE_WITHDRAW_SUCCESS				= new string_id("base_player","prose_withdraw_success");
const string_id PROSE_TRANSFER_SUCCESS				= new string_id("base_player","prose_transfer_success");

const string DICT_PLAYER_ID							= "player_id";
const string DICT_TARGET_ID							= "target_id";
const string DICT_TARGET_NAME						= "target_name";
const string DICT_ACCT_NAME							= "account_name";
const string DICT_AMOUNT							= "amount";
const string DICT_TOTAL								= "total";
const string DICT_MSG_PAYER							= "msg_payer";

const string DICT_NOTIFY							= "notify";

const string DICT_HANDLER							= "returnHandler";
const string DICT_CODE								= "returnCode";

const string DICT_PAY_HANDLER						= "payHandler";

const string DICT_OTHER								= "other";

const string DICT_BANK_ACTION						= "bankAction";

const int BA_NONE									= 0;
const int BA_DEPOSIT								= 1;
const int BA_WITHDRAW								= 2;
const int BA_TRANSFER								= 3;

const int RET_SUCCESS								= 0;
const int RET_FAIL									= 1;

//AI LOOT HANDLERS
const string HANDLER_REQUEST_LOOT_ADD				= "handleRequestLootAdd";

const string HANDLER_LOOT_ADD_PASS					= "handleLootAddPass";
const string HANDLER_LOOT_ADD_FAIL					= "handleLootAddFail";

const string HANDLER_LOOT_WITHDRAW_PASS				= "handleLootWithdrawPass";
const string HANDLER_LOOT_WITHDRAW_FAIL				= "handleLootWithdrawFail";

/***** NAMED ACCOUNTS **************************************************/

//     ***** PLEASE MAKE SURE TO ADD THE ACCOUNT TO STF "money/acct_n" *********
const string STF_ACCT_N								= "money/acct_n";

//CHARACTER CREATION ACCOUNT
const string ACCT_CHARACTER_CREATION				= "characterCreation";

//NEWBIE TUTORIAL ACCOUNT
const string ACCT_NEWBIE_TUTORIAL					= "newbieTutorial";
const string ACCT_NEW_PLAYER_QUESTS					= "newPlayerQuests";

//CUSTOMER SERVICE ACCOUNT
const string ACCT_CUSTOMER_SERVICE					= "customerService";

//NAMED SYSTEM ACCOUNTS
const string ACCT_MISSION_DYNAMIC                   = "missionSystemDynamic";
const string ACCT_MISSION_PLAYER                    = "missionSystemPlayer";
const string ACCT_BOUNTY                            = "bountySystem";
const string ACCT_BOUNTY_CHECK                          = "bountyCheckSystem";

const string ACCT_CLONING                           = "cloningSystem";
const string ACCT_INSURANCE                         = "insuranceSystem";

const string ACCT_TRAVEL                            = "travelSystem";
const string ACCT_SHIPPING                          = "shippingSystem";

const string ACCT_BAZAAR                            = "bazaarSystem";
const string ACCT_DISPENSER			    			= "dispenserSystem";

const string ACCT_SKILL_TRAINING					= "skillTrainingSystem";

const string ACCT_DEED_RECLAIM						= "deedReclaim";
const string ACCT_STRUCTURE_DESTROYED				= "structureDestroyed";

const string ACCT_VEHICLE_REPAIRS					= "vehicleRepairs";

//NAMED FACTION ACCOUNTS
const string ACCT_REBEL                             = "rebelFaction";
const string ACCT_IMPERIAL                          = "imperialFaction";

//QUEST ACCOUNTS
const string ACCT_JABBA								= "jabbasPalace";
const string ACCT_POI								= "POISystem";
const string ACCT_CRAFTING_JOB						= "craftingJob";
const string ACCT_CROWD_PLEASER						= "crowdPleaser";

const string ACCT_EP3_HUNTING_GROUNDS				= "ep3HuntingGrounds";
const string ACCT_GROUND_QUEST						= "groundQuest";

const string ACCT_PGC_PLAYER_DONATED				= "pgc_player_donated_credits";

//MISC ACCOUNTS
const string ACCT_CORPSE_EXPIRATION					= "corpseExpiration";
const string ACCT_TEST								= "testing";
const string ACCT_STRUCTURE_MAINTENANCE		    	= "structureMaintanence"; // misspelled, left because web reports are using it
const string ACCT_TIP_SURCHARGE						= "tipSurcharge";
const string ACCT_VENDOR							= "vendorMaintanence";
const string ACCT_CITY								= "cityMaint";
const string ACCT_JEDI_DEATH						= "jediDeath";

const string ACCT_TIP_ESCROW						= "tipEscrow";

//MISC NPC ACCOUNTS
const string ACCT_NPC_LOOT							= "npcLoot";
const string ACCT_JUNK_DEALER						= "junkDealer";
const string ACCT_RELIC_DEALER						= "relicDealer";

const string ACCT_CANTINA_DRINK						= "cantinaDrink";

//TESTING ACCOUNT
const string ACCT_BETA_TEST							= "betaTest";

//ERROR ACCOUNTS
const string ACCT_BAD_SPLIT							= "badGroupCoinSplit";

//GAMBLING ACCOUNTS
const string ACCT_SLOT_STANDARD						= "gamblingSlotStandard";

const string ACCT_ROULETTE							= "gamblingRoulette";

const string ACCT_CARD_SABACC						= "gamblingCardSabacc";

//CONTRABAND SCANNING FINES
const string ACCT_FINES								= "contraband_fines";

//STORMTROOPER RESPECT FINES
const string ACCT_ST_FINES						= "stormtrooper_fines";

//PERFORMER ESCROW
const string ACCT_PERFORM_ESCROW					= "tipescrow";

// SPACE ACCOUNTS
const string ACCT_SPACE_QUEST_REWARD				="spaceQuestReward"; // Auto reward account.


//constant human readable values
const int MILLION					= 1000000;
const int BILLION					= 1000000000;
const int HUNDRED_MILLION				= 100000000;

/***** BASE FUNCTIONS **************************************************/
/*****************************************************************
 * @brief depositCashToBank() overload function
 *
 * @param obj_id	player
 * @param int		amt
 *
 * @return boolean; false on error
 ******************************************************************/
boolean deposit(obj_id player, int amt)
{
	if ( player != null && amt != 0 )
	{
		dictionary d = new dictionary();
		d.put(DICT_PLAYER_ID, player);
		d.put(DICT_AMOUNT, amt);
		d.put(DICT_BANK_ACTION, BA_DEPOSIT);

		return depositCashToBank(player, amt, HANDLER_BANK_SUCCESS, HANDLER_BANK_DEPOSIT_ERROR, d);
	}
	else if (player != null)
		return true;

	// player == null
	debugServerConsoleMsg(null, "ERROR in money.scriptlib:deposit - player == null!");
	return false;
}

/*****************************************************************
 * @brief withdrawCashFromBank() overload function
 *
 * @param obj_id	player
 * @param int		amt
 *
 * @return boolean; false on error
 ******************************************************************/
boolean withdraw(obj_id player, int amt)
{
	dictionary d = new dictionary();
	d.put(DICT_PLAYER_ID, player);
	d.put(DICT_AMOUNT, amt);
	d.put(DICT_BANK_ACTION, BA_WITHDRAW);

	return withdrawCashFromBank(player, amt, HANDLER_BANK_SUCCESS, HANDLER_BANK_WITHDRAW_ERROR, d);
}

/*****************************************************************
 * @brief depositCashToBank() overload function
 *
 * @param obj_id	player
 * @param obj_id	target
 * @param int		amt
 *
 * @return boolean; false on error
 ******************************************************************/
boolean cashTo(obj_id player, obj_id target, int amt)
{
	dictionary d = new dictionary();
	d.put(DICT_PLAYER_ID, player);
	d.put(DICT_TARGET_ID, target);
	d.put(DICT_AMOUNT, amt);

	return transferCashTo(player, target, amt, HANDLER_BANK_SUCCESS, HANDLER_CREDIT_TRANSFER_ERROR, d);
}

/*****************************************************************
 * @brief depositCashToBank() overload function
 *
 * @param obj_id	player
 * @param obj_id	target
 * @param int		amt
 *
 * @return boolean; false on error
 ******************************************************************/
boolean bankTo(obj_id player, obj_id target, int amt)
{
	dictionary d = new dictionary();
	d.put(DICT_PLAYER_ID, player);
	d.put(DICT_TARGET_ID, target);
	d.put(DICT_AMOUNT, amt);

	return transferBankCreditsTo(player, target, amt, HANDLER_BANK_SUCCESS, HANDLER_BANK_TRANSFER_ERROR, d);
}

/*****************************************************************
 * @brief depositCashToBank() overload function
 *
 * @param obj_id	player
 * @param obj_id	target
 * @param int		amt
 *
 * @return boolean; false on error
 ******************************************************************/
boolean bankTo(string acct, obj_id target, int amt)
{
	dictionary d = new dictionary();
	d.put(DICT_TARGET_ID, target);
	d.put(DICT_ACCT_NAME, acct);
	d.put(DICT_AMOUNT, amt);
	d.put(DICT_BANK_ACTION, BA_TRANSFER);

	boolean boolReturn = transferBankCreditsFromNamedAccount(acct, target, amt, HANDLER_BANK_SUCCESS, HANDLER_BANK_TRANSFER_ERROR, d);
	utils.moneyInMetric(target, acct, amt);
	return boolReturn;
}

/*****************************************************************
 * @brief depositCashToBank() overload function
 *
 * @param obj_id	player
 * @param obj_id	target
 * @param int		amt
 *
 * @return boolean; false on error
 ******************************************************************/
boolean bankTo(obj_id player, string acct, int amt)
{
	dictionary d = new dictionary();
	d.put(DICT_PLAYER_ID, player);
	d.put(DICT_ACCT_NAME, acct);
	d.put(DICT_AMOUNT, amt);

	boolean boolReturn = transferBankCreditsToNamedAccount(player, acct, amt, HANDLER_BANK_SUCCESS, HANDLER_BANK_TRANSFER_ERROR, d);


	utils.moneyOutMetric(player, acct, amt);
	return boolReturn;
}


boolean bankTo(obj_id player, string acct, int amt, dictionary dctParams)
{

	dctParams.put(DICT_PLAYER_ID, player);
	dctParams.put(DICT_ACCT_NAME, acct);
	dctParams.put(DICT_AMOUNT, amt);
	obj_id self = getSelf();
	obj_id objSender = null;
	if(utils.hasScriptVar(self, "objSender"))
	{
		objSender = utils.getObjIdScriptVar(self, "objSender");
	}
	if(isIdValid(objSender))
	{
		sendSystemMessageTestingOnly(objSender, "Sending money");
	}
	boolean boolReturn = transferBankCreditsToNamedAccount(player, acct, amt, HANDLER_BANK_SUCCESS, HANDLER_BANK_TRANSFER_ERROR, dctParams);
	if(isIdValid(objSender))
	{
		sendSystemMessageTestingOnly(objSender, "Sent money, return was "+boolReturn);
		sendSystemMessageTestingOnly(objSender, "Player : "+player);
		sendSystemMessageTestingOnly(objSender, "Acct is "+acct);
		sendSystemMessageTestingOnly(objSender, "Amt is "+amt);
		if(dctParams!=null)
		{
			sendSystemMessageTestingOnly(objSender, "Params "+dctParams.toString());
		}
		else
		{
			sendSystemMessageTestingOnly(objSender , "Params NULL!");
		}

	}

	utils.moneyOutMetric(player, acct, amt);
	return boolReturn;
}


/*****************************************************************
 * @brief determines if a player has cash credits greater than
 *			or equal to the specified amount
 *
 * @param obj_id	player
 * @param int		type
 * @param int		amt
 *
 * @return boolean; false on error
 ******************************************************************/
boolean hasFunds(obj_id player, int type, int amt)
{
 	if ( !isIdValid(player) )
 	{
 		return false;
 	}

 	int bal = 0;
 	switch(type)
 	{
 		case MT_CASH:
 			bal = getCashBalance(player);
 			break;

 		case MT_BANK:
 			bal = getBankBalance(player);
 			break;

 		case MT_TOTAL:
 			bal = getTotalMoney(player);
 			break;

 		default:
 			debugSpeakMsg(player, "money:hasFunds was passed an out of bounds money type");
 			return false;
 	}

 	if ( bal >= amt )
 	{
 		return true;
 	}
 	else
 	{
 		return false;
 	}
}

/***** COVERT TRANSACTION FUNCTIONS *********************************************/
/*****************************************************************
 * @brief behind-the-scenes deposit... useful for faking cash to named acct transactions
 *
 * @param obj_id	player
 * @param int		amt
 *
 * @return boolean; false on error
 ******************************************************************/
boolean covertDeposit(obj_id player, int amt, string returnHandler, dictionary oldparams)
{
	dictionary params = new dictionary();
	if ( oldparams != null && !oldparams.isEmpty() )
	{
		java.util.Enumeration keys = oldparams.keys();
		while ( keys.hasMoreElements() )
		{
			Object key = keys.nextElement();
			params.put(key, oldparams.get(key));
		}
	}

	params.put(DICT_PLAYER_ID, player);
	params.put(DICT_AMOUNT, amt);
	params.put(DICT_HANDLER, returnHandler);

	LOG("money", player+" is attempting to covert deposit "+amt+" credits");
	return depositCashToBank(player, amt, HANDLER_COVERT_SUCCESS, HANDLER_COVERT_ERROR, params);
}

/***** PAY FUNCTIONS *********************************************/
/*****************************************************************
 * @brief attempts to transfer amt from payer to target - bank then cash credits
 * 	 		the function kicks out to the targetReturnHandler with PASS/FAIL code
 *
 * @param obj_id	payer
 * @param obj_id	target
 * @param int		amt
 * @param string	targetReturnHandler
 * @param dict		params
 *
 * @return boolean; false on error
 ******************************************************************/
boolean requestPayment(obj_id payer, obj_id target, int amt, string returnHandler, dictionary oldparams, boolean notifySuccess)
{
	if ( !isIdValid(payer) || !payer.isLoaded() || !isIdValid(target) || amt < 1 )
		return false;

	if( !hasScript(payer, "player.player_money") )
		attachScript(payer, "player.player_money");

	dictionary params = new dictionary();
	if ( oldparams != null && !oldparams.isEmpty() )
	{
		java.util.Enumeration keys = oldparams.keys();
		while ( keys.hasMoreElements() )
		{
			Object key = keys.nextElement();
			params.put(key, oldparams.get(key));
		}
	}

	params.put(DICT_PLAYER_ID, payer);
	params.put(DICT_TARGET_ID, target);
	params.put(DICT_AMOUNT, amt);
	params.put(DICT_TOTAL, amt);
	params.put(DICT_HANDLER, returnHandler);
	params.put(DICT_NOTIFY, notifySuccess);

	int total = getTotalMoney(payer);
	if ( total < amt )
	{
		params.put(DICT_CODE, RET_FAIL);
		return messageTo(target, returnHandler, params, 0, isObjectPersisted(target));
	}

	return messageTo(payer, HANDLER_PAYMENT_REQUEST, params, 0, isObjectPersisted(payer));
}

boolean requestPayment(obj_id payer, obj_id target, int amt, string returnHandler, dictionary params)
{
	return requestPayment(payer, target, amt, returnHandler, params, true);
}

/*****************************************************************
 * @brief attempts to transfer amt from payer to target - bank then cash credits
 * 	 		the function kicks out to the targetReturnHandler with PASS/FAIL code
 *
 * @param obj_id	payer
 * @param obj_id	target
 * @param int		amt
 * @param string	targetReturnHandler
 * @param dict		params
 *
 * @return boolean; false on error
 ******************************************************************/
boolean requestPayment(obj_id payer, string acct, int amt, string returnHandler, dictionary oldparams, boolean notifySuccess)
{
	if ( !isIdValid(payer) || !payer.isLoaded() || acct == null || acct.equals("") || amt < 1 )
	{
		return false;
	}

	if( !hasScript(payer, "player.player_money") )
		attachScript(payer, "player.player_money");

	dictionary params = new dictionary();
	if ( oldparams != null && !oldparams.isEmpty() )
	{
		java.util.Enumeration keys = oldparams.keys();
		while ( keys.hasMoreElements() )
		{
			Object key = keys.nextElement();
			params.put(key, oldparams.get(key));
		}
	}

	params.put(DICT_PLAYER_ID, payer);
	params.put(DICT_TARGET_ID, obj_id.NULL_ID);
	params.put(DICT_ACCT_NAME, acct);
	params.put(DICT_AMOUNT, amt);
	params.put(DICT_TOTAL, amt);
	params.put(DICT_HANDLER, returnHandler);
	params.put(DICT_NOTIFY, notifySuccess);

	int total = getTotalMoney(payer);
	if ( total < amt )
	{
		obj_id npc = params.getObjId("npc");
		params.put(DICT_CODE, RET_FAIL);
		if(returnHandler != null && !returnHandler.equals(""))
			messageTo(npc, returnHandler, params, 0, isObjectPersisted(npc));
		return false;
	}

	return messageTo(payer, HANDLER_PAYMENT_REQUEST, params, 0, isObjectPersisted(payer));
}

boolean requestPayment(obj_id payer, string acct, int amt, string returnHandler, dictionary params)
{
	return requestPayment(payer, acct, amt, returnHandler, params, true);
}

/*****************************************************************
 * @brief attempts to transfer amt from self to target - bank then cash credits
 * 	 		the function kicks out to the targetReturnHandler with PASS/FAIL code
 *
 *	WARNING: this function should only be called by SELF. if not, use requestPayment()
 *
 *	NOTE: pay() does not handle successful payment message. it is up to TARGET via
 *			returnHandler to provide success player feedback
 *
 * @param obj_id	self
 * @param obj_id	target
 * @param int		amt
 * @param string	returnHandler
 * @param dict		params
 *
 * @return boolean; false on error
 ******************************************************************/
boolean pay(obj_id self, obj_id target, int amt, string returnHandler, dictionary oldparams, boolean notifySuccess)
{
	if ( !isIdValid(self) || !self.isLoaded() || target == null || amt < 1 )
		return false;

	obj_id callingSelf = getSelf();
	if ( isIdValid(callingSelf) && callingSelf != self )
		return requestPayment(self, target, amt, returnHandler, oldparams, notifySuccess);

	if( !hasScript(self, "player.player_money") )
		attachScript(self, "player.player_money");

	dictionary params = new dictionary();
	if ( oldparams != null && !oldparams.isEmpty() )
	{
		java.util.Enumeration keys = oldparams.keys();
		while ( keys.hasMoreElements() )
		{
			Object key = keys.nextElement();
			params.put(key, oldparams.get(key));
		}
	}

	params.put(DICT_PLAYER_ID, self);
	params.put(DICT_TARGET_ID, target);
	params.put(DICT_AMOUNT, amt);
	params.put(DICT_TOTAL, amt);
	params.put(DICT_PAY_HANDLER, returnHandler);
	params.put(DICT_NOTIFY, notifySuccess);

	//debugSpeakMsg(self, "money::pay - " + params.toString());

	int total = getTotalMoney(self);
	int bank = getBankBalance(self);
	bank -= getIntObjVar(self, VAR_PAY_TALLY);

	if ( total < amt )
	{
		prose_package pp = prose.getPackage(PROSE_PAY_NSF, self, target, amt);
		sendSystemMessageProse(self, pp);
		params.put(DICT_CODE, RET_FAIL);
		return messageTo(target, returnHandler, params, 0, isObjectPersisted(target));
	}

	//attachScript(self, SCRIPT_PAY_ACTOR);

	if ( bank >= amt )
	{
		return transferBankCreditsTo(self, target, amt, HANDLER_PAY_PASS, HANDLER_PAY_FAIL, params);
	}
	else
	{
		int diff = amt - bank;

		incrementPayTally(self, diff);
		return covertDeposit(self, diff, HANDLER_PAY_DEPOSIT, params);
	}
}

boolean pay(obj_id self, obj_id target, int amt, string returnHandler, dictionary params)
{
	return pay(self, target, amt, returnHandler, params, true);
}

/*****************************************************************
 * @brief attempts to transfer amt from self to target - bank then cash credits
 * 	 		the function kicks out to the targetReturnHandler with PASS/FAIL code
 *
 *	WARNING: this function should only be called by SELF. if not, use requestPayment()
 *
 *	NOTE: pay() does not handle successful payment message. it is up to TARGET via
 *			returnHandler to provide success player feedback
 *
 * @param obj_id	self
 * @param obj_id	target
 * @param int		amt
 * @param string	returnHandler
 * @param dict		params
 *
 * @return boolean; false on error
 ******************************************************************/
boolean pay(obj_id self, string acct, int amt, string returnHandler, dictionary oldparams, boolean notifySuccess)
{
	if ( !isIdValid(self) || !self.isLoaded() || acct == null || acct.equals("") || amt < 1 )
		return false;

	obj_id callingSelf = getSelf();
	if ( isIdValid(callingSelf) && callingSelf != self )
		return requestPayment(self, acct, amt, returnHandler, oldparams, notifySuccess);

	if( !hasScript(self, "player.player_money") )
		attachScript(self, "player.player_money");

	dictionary params = new dictionary();
	if ( oldparams != null && !oldparams.isEmpty() )
	{
		java.util.Enumeration keys = oldparams.keys();
		while ( keys.hasMoreElements() )
		{
			Object key = keys.nextElement();
			params.put(key, oldparams.get(key));
		}
	}

	params.put(DICT_PLAYER_ID, self);
	//params.put(DICT_TARGET_ID, obj_id.NULL_ID);
	params.put(DICT_ACCT_NAME, acct);
	params.put(DICT_AMOUNT, amt);
	params.put(DICT_TOTAL, amt);
	params.put(DICT_PAY_HANDLER, returnHandler);
	params.put(DICT_NOTIFY, notifySuccess);

	//debugSpeakMsg(self, "money::pay - " + params.toString());

	int total = getTotalMoney(self);
	int bank = getBankBalance(self);
	bank -= getIntObjVar(self, VAR_PAY_TALLY);

	/*
	if ( total < amt )
	{
		return false;
	}
	*/

	if ( total < amt )
	{
		params.put(DICT_CODE, RET_FAIL);
		return messageTo(self, returnHandler, params, 0, isObjectPersisted(self));
	}

	//attachScript(self, SCRIPT_PAY_ACTOR);

	if ( bank >= amt )
	{
		LOG("money", "PAY: "+self+" is transfering "+amt+" bank credits to acct: "+acct);
		boolean boolReturn = transferBankCreditsToNamedAccount(self, acct, amt, HANDLER_PAY_PASS, HANDLER_PAY_FAIL, params);
		utils.moneyOutMetric(self, acct, amt);
		return boolReturn;
	}
	else
	{
		LOG("money", "PAY: "+self+" NSF bank credits to xfer "+amt+" credits to acct: "+acct+" -> covert deposit");
		int diff = amt - bank;

		incrementPayTally(self, diff);

		return covertDeposit(self, diff, HANDLER_PAY_DEPOSIT, params);
	}
}

boolean pay(obj_id self, string acct, int amt, string returnHandler, dictionary params)
{
	return pay(self, acct, amt, returnHandler, params, true);
}

void incrementPayTally(obj_id self, int amt)
{
	if ( !isIdValid(self) || amt < 1 )
		return;

	int tally = getIntObjVar(self, VAR_PAY_TALLY);
	setObjVar(self, VAR_PAY_TALLY, tally+amt);
}

void decrementPayTally(obj_id self, dictionary params)
{
	if ( !isIdValid(self) || params == null || params.isEmpty() )
		return;

	int amt = params.getInt(DICT_AMOUNT);
	int tally = getIntObjVar(self, VAR_PAY_TALLY);

	tally -= amt;
	if ( tally <= 0 )
		removeObjVar(self, VAR_PAY_TALLY);
	else
		setObjVar(self, VAR_PAY_TALLY, tally);
}

/*****************************************************************
 * @brief attempts to transfer amt from self to target - bank then cash credits
 * 	 		the function kicks out to the targetReturnHandler with PASS/FAIL code
 *
 *	WARNING: this function should only be called by SELF. if not, use requestPayment()
 *
 *	NOTE: pay() does not handle successful payment message. it is up to TARGET via
 *			returnHandler to provide success player feedback
 *
 * @param obj_id	self
 * @param obj_id	target
 * @param int		amt
 * @param string	returnHandler
 * @param dict		params
 *
 * @return boolean; false on error
 ******************************************************************/
boolean systemPayout(string acct, obj_id target, int amt, string returnHandler, dictionary oldparams)
{
	if ( (acct == null) || (acct.equals("")) )
	{
		return false;
	}

	obj_id self = getSelf();
	if( !hasScript(self, "player.player_money") )
		attachScript(self, "player.player_money");

	if ( !isIdValid(target) )
	{
		return false;
	}

	if ( amt < 1 )
	{
		return false;
	}

	dictionary params = new dictionary();
	if ( oldparams != null && !oldparams.isEmpty() )
	{
		java.util.Enumeration keys = oldparams.keys();
		while ( keys.hasMoreElements() )
		{
			Object key = keys.nextElement();
			params.put(key, oldparams.get(key));
		}
	}

	if (returnHandler == null)
		returnHandler = "test";

	params.put(DICT_PLAYER_ID, self);
	params.put(DICT_ACCT_NAME, acct);
	params.put(DICT_TARGET_ID, target);
	params.put(DICT_AMOUNT, amt);
	params.put(DICT_PAY_HANDLER, returnHandler);

	//attachScript(self, SCRIPT_ACCT_PAY);

	boolean boolReturn =  transferBankCreditsFromNamedAccount(acct, target, amt, "acctToPass", "xferFail", params);
	utils.moneyInMetric(target, acct, amt);
	return boolReturn;
}

/***** REPORT FUNCTIONS *********************************************/
/*****************************************************************
 * @brief notifies the player of banking success
 *
 * @param obj_id	player
 *
 * @return boolean; false on error
 ******************************************************************/
boolean bankSuccess(obj_id player, dictionary params)
{
 	if ( !isIdValid(player) )
 		return false;

	if ( params == null || params.isEmpty() )
	{
 		sendSystemMessage(player, SID_BANK_SUCCESS);
 		return true;
 	}

 	prose_package pp = null;

 	int bankAction = params.getInt("bankAction");
 	int amt = params.getInt(DICT_AMOUNT);
 	if ( amt > 0 )
 	{
		switch ( bankAction )
		{
			case BA_DEPOSIT:
				pp = prose.getPackage(PROSE_DEPOSIT_SUCCESS, amt);
				break;

			case BA_WITHDRAW:
				pp = prose.getPackage(PROSE_WITHDRAW_SUCCESS, amt);
				break;

			case BA_TRANSFER:
				pp = prose.getPackage(PROSE_TRANSFER_SUCCESS, amt);
				break;
		}
	}

 	if ( pp == null )
	{
 		sendSystemMessage(player, SID_BANK_SUCCESS);
 		return true;
 	}

 	sendSystemMessageProse(player, pp);
 	return true;
}

boolean bankSuccess(obj_id player)
{
	return bankSuccess(player, null);
}
/*****************************************************************
 * @brief notifies the player of unknown banking error
 *
 * @param obj_id	player
 *
 * @return boolean; false on error
 ******************************************************************/
boolean bankError(obj_id player)
{
 	if ( !isIdValid(player) )
 	{
 		return false;
 	}

 	sendSystemMessage(player, SID_BANK_ERROR);
 	return true;
}

/*****************************************************************
 * @brief notifies the player of bank withdraw error
 *
 * @param obj_id	player
 *
 * @return boolean; false on error
 ******************************************************************/
boolean bankWithdrawError(obj_id player)
{
 	if ( !isIdValid(player) )
 	{
 		return false;
 	}

 	sendSystemMessage(player, SID_BANK_WITHDRAW_ERROR);
 	return true;
}

/*****************************************************************
 * @brief notifies the player of bank deposit error
 *
 * @param obj_id	player
 *
 * @return boolean; false on error
 ******************************************************************/
boolean bankDepositError(obj_id player)
{
 	if ( !isIdValid(player) )
 	{
 		return false;
 	}

 	sendSystemMessage(player, SID_BANK_DEPOSIT_ERROR);
 	return true;
}

/*****************************************************************
 * @brief notifies the player of bank transfer error
 *
 * @param obj_id	player
 *
 * @return boolean; false on error
 ******************************************************************/
boolean bankTransferError(obj_id player)
{
 	if ( !isIdValid(player) )
 	{
 		return false;
 	}

 	sendSystemMessage(player, SID_BANK_TRANSFER_ERROR);
 	return true;
}

/*****************************************************************
 * @brief notifies the player of cash transfer error
 *
 * @param obj_id	player
 *
 * @return boolean; false on error
 ******************************************************************/
boolean cashTransferError(obj_id player)
{
 	if ( !isIdValid(player) )
 	{
 		return false;
 	}

 	sendSystemMessage(player, SID_CASH_TRANSFER_ERROR);
 	return true;
}

/*****************************************************************
 * @brief notifies the player of cash transfer error
 *
 * @param obj_id	player
 *
 * @return boolean; false on error
 ******************************************************************/
boolean nullTransactionError(obj_id player)
{
 	if ( !isIdValid(player) )
 	{
 		return false;
 	}

 	sendSystemMessage(player, SID_NULL_TRANSACTION_ERROR);
 	return true;
}

/*****************************************************************
 * @brief requests that the creature broker its own loot addition
 *
 * @param obj_id	creature
 *
 * @return boolean; false on error
 ******************************************************************/
boolean requestLootAdd(obj_id creature, int amt)
{
 	if ( !isIdValid(creature) || !isMob(creature) || isPlayer(creature) )
 	{
 		return false;
 	}

 	dictionary d = new dictionary();
 	d.put(DICT_AMOUNT, amt);

 	return messageTo(creature, HANDLER_REQUEST_LOOT_ADD, d, 0, false);
}

/*****************************************************************
 * @brief transfers cash from named acct to creature inventory
 *
 * @param obj_id	creature
 * @param int		amt
 *
 * @return boolean; false on error
 ******************************************************************/
boolean addCreatureLoot(obj_id creature, int amt)
{
 	if ( !isIdValid(creature) || !isMob(creature) || isPlayer(creature) || amt <= 0 )
 		return false;

 	dictionary d = new dictionary();
 	d.put(DICT_AMOUNT, amt);

 	boolean boolReturn = transferBankCreditsFromNamedAccount(ACCT_NPC_LOOT, creature, amt, HANDLER_LOOT_ADD_PASS, HANDLER_LOOT_ADD_FAIL, d);
	utils.moneyInMetric(creature, ACCT_NPC_LOOT, amt);
 	return boolReturn;
}

/***** SUPPORT FUNCTIONS *********************************************/
/*****************************************************************
 * @brief attempts to retrieve the return code embedded in the passed dictionary
 *
 * @param dictionary	params
 *
 * @return int; -1 on error
 ******************************************************************/
int getReturnCode(dictionary params)
{
	if ( (params == null) || (params.isEmpty()) )
	{
		return -1;
	}

	java.util.Enumeration e = params.keys();
	while ( e.hasMoreElements() )
	{
		string key = (string)e.nextElement();
		if ( key.equals(DICT_CODE) )
		{
			return params.getInt(key);
		}
	}

	return -1;
}

void clearTotalPlayerCredits(obj_id player, string acct)
{
	if ( !isIdValid(player) || !isPlayer(player) || acct == null || acct.equals("") )
		return;

	//attachScript(player, "money.clear.target");

	dictionary d = new dictionary();
	d.put("acct", acct);
	messageTo(player, "handleCovertDepositReturn", d, 1f, false);
}