Raocoin2.lua

CURRENTLY UNRELEASED

The Raocoin2 library allows the creation of customisable currencies, which can be saved between plays. It also provides a built-in shop framework to allow these currencies to be used for various tasks.

Installation

Place the file raocoin2.lua and the folder named raocoin into the LuaScriptsLib folder.

How to use

To enable the Raocoin2 library for a specific set of levels, add this line to lunaworld.lua:

raocoin = loadSharedAPI("raocoin2");

Then, define a currency my registering either an NPC item to count, or a global memory address to reference. This example will count dragon coins, and display a UI element at the point (472, 66) (just under the score):

dragoncoins = raocoin.registerCurrency(274, true, 472, 66);

While this example will assign a reference to the existing HUD coin counter, allowing regular coins to be saved, loaded, and used as currency:

coins = raocoin.registerMemCurrency(0x00B2C5A8,FIELD_WORD,true,false);

Each of these functions returns a Currency object, which can be used to create shops and store values between plays.

Documentation

Constants

These are static values that should be treated as read-only

CODE_CANTAFFORD	ErrorCode	Used by the "onBuyFail" event to pass information about the failure.
CODE_ALREADYBOUGHT	ErrorCode	Used by the "onBuyFail" event to pass information about the failure.

Fields

These are variables you can access

IMG_TOKEN_T	LuaImageResource	The temporary shop token sprite. When replacing this, the sprite should be 32x64, in order to retain correct alignments.
IMG_TOKEN_P	LuaImageResource	The permanent shop token sprite. When replacing this, the sprite should be 32x64, in order to retain correct alignments.
IMG_ARROW	LuaImageResource	The arrow image used when a shop token can be interacted with. When replacing this, the sprite should be 32x32, in order to retain correct alignments.

Classes

These are internal classes that you can create and access using the API

Currency

The Currency class stores and retains a value for the currencies that have been registered to the game. Currency objects are created using "registerCurrency" or "registerMemCurrency"

Fields

visible	boolean	Determines whether or not the currency will display a UI element.
img	LuaImageResource	Contains the image holding the currency's UI element.
x	number	The x-coordinate in screen space of the upper-left corner of the UI element.
y	number	The y-coordinate in screen space of the upper-left corner of the UI element.
path	string	The file path of the image contained in the "img" field.
id	number:read-only	The currency ID (for NPC-based currencies, this is the NPC ID. For mem-based currencies, this is the memory address).
type	number:read-only	The type of the currency. For NPC-based currencies, this is always -1. For mem-based currencies, this will hold the memory access type (e.g. "FIELD_WORD").

Functions

Currency:refreshUI
Reloads the UI image stored in "path". Call this if the image path changes.	nil
Currency:get
Returns the current value of this currency.	number
Currency:set		value
Sets the currency value, but does not save it to the disk.	nil	number The value to set the currency to.
Currency:save
Flushes the currency value to the disk, allowing it to be reloaded between levels and sessions.	nil
Currency:addItem		price	actions	permanent	id
Creates a new item that can be bought with this currency.	Item	number The price of the item in this currency.	function The actions to execute when this item is bought, or when the level is loaded after buying it (provided "permanent" is true).	boolean:optional Whether the item should be a permanent purchase (buy once and keep forever, even across sessions) or a repeatable one. Defaults to true.	number:optional The ID of this specific item, used by the save system to ensure items' purchase state is correctly stored. Repeated IDs will share purchase state.

---

Item

The Item class stores an object that can be bought by calling "buy". Item objects are specific to a single currency

Fields

id	number:read-only	The item ID. This is a unique ID used by the save system to ensure items are saved and loaded correctly.
currency	Currency	The currency this item is associated with.
price	number	The price of this item.
permanent	boolean	Is this item a permanent purchase?
actions	function	The actions to perform when this item is bought.

Functions

Item:canAfford
Determines if the player has enough of the specified currency to buy this item.	boolean
Item:showPrice		x	y	screenSpace
Displays the item's price on the screen.	nil	number The x-coordinate of the top left of the price display.	number The y-coordinate of the top left of the price display.	boolean Are these coordinates in screen space or world space? Defaults to true (screen space).
Item:buy
Attempts to buy the item. This function will call "onBuyFail" or "onBuy" depending on the result.	nil
Item:forceGet
Forcibly buys the item without performing any price checks or deducting from the currency.	nil
Item:isBought
Determines if a permanent purchase has been previously bought. Is always false for repeatable purchases.	boolean
Item:undoBuy
Reverts a permanent purchase. Will not refund the currency.	nil
Item:placeToken		x	y	section	npcid	text	image
Places a shop token in the world, which can be used to buy the item. Shop tokens are 3 blocks high (though can be walked through), and can be bought by holding the "down" key when in front of the bottom block.	nil	number The x-coordinate of the bottom block in world space.	number The y-coordinate of the bottom block in world space.	number The section to place the token in (0 = section 1).	number:optional The ID of an NPC to display above the shop token. The NPC will not interact with the world in any way, and will simply act as an icon. No NPC will be placed if left blank.	string:optional Text to display over the token. No text will be drawn if left blank.	LuaImageResource:optional An image to display over the token. No image will be drawn if left blank.
Item:removeToken
Removes a previously placed shop token.	nil

Functions

These are functions you will need to use the library

registerCurrency		npcID	showUI	UIx	UIy	imgPath
Creates a new Currency object, based around an NPC ID.	Currency	number The ID of the NPC to count for this currency.	boolean:optional Should this currency display its own UI element or not? Defaults to false.	number:optional The x-coordinate of the top-left corner of the UI object in screen space. Defaults to 0.	number:optional The y-coordinate of the top-left corner of the UI object in screen space. Defaults to 0.	string:optional The path of the image to use for the UI object. Defaults to "dragoncoin.png", found in the "raocoin" folder.
registerMemCurrency		address	memtype	restore	showUI	UIx	UIy	imgPath
Similar to registerCurrency, Creates a new Currency object, but based around a global memory location.	Currency	number The memory address to reference for this currency.	number The memory type (e.g. FIELD_WORD) to use when accessing this address.	boolean:optional Should this currency restore its value from the saved one when the game loads? Defaults to true.	boolean:optional Should this currency display its own UI element or not? Defaults to false.	number:optional The x-coordinate of the top-left corner of the UI object in screen space. Defaults to 0.	number:optional The y-coordinate of the top-left corner of the UI object in screen space. Defaults to 0.	string:optional The path of the image to use for the UI object. Defaults to "dragoncoin.png", found in the "raocoin" folder.
getCurrency		npcID
Returns the currency associated with the specified NPC ID.	Currency	number The NPC ID to find the currency for.
getMemCurrency		address
Returns the currency associated with the specified memory address.	Currency	number The address to find the currency for.
addItem		currency	price	actions	permanent	id
Equivalent to "Currecny:addItem". Creates a new item that can be bought with the specified currency.	Item	Currency The currency to associate with this item.	number The price of the item in this currency.	function The actions to execute when this item is bought, or when the level is loaded after buying it (provided "permanent" is true).	boolean:optional Whether the item should be a permanent purchase (buy once and keep forever, even across sessions) or a repeatable one. Defaults to true.	number:optional The ID of this specific item, used by the save system to ensure items' purchase state is correctly stored. Repeated IDs will share purchase state.
getScreenBounds
Gets the current boundaries of the screen, taking into account the player location and the section boundaries. The resulting table contains values "left", "right", "top" and "bottom", giving coordinates in world space.	table of number
worldToScreen		x	y
Converts the given world coordinates to screen coordinates.	number,number	number The x-coordinate to convert.	number The y-coordinate to convert.

Events

These are customisable events that can be used in lunadll.lua to run user-specified code

onCollect	currency
Called when any currency counter is incremented.	Currency The currency whose counter increased.
onBuy	item
Called when an item is successfully bought. Not called when a level is loaded and an item has already been bought.		Item The item that was bought.
onBuyFail	item	code
Called when an item is attempted to be bought, but the attempt failed.	Item The item that was attempted bought.	ErrorCode The code containing the reason for the failure. If the player could not afford the item, this contains CODE_CANTAFFORD. If the player has already bought the item, then this contains CODE_ALREADYBOUGHT.

---