Raocoin2.lua

From PGE Wiki
Jump to: navigation, search

Download here (v2.0.10)

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:

local raocoin = API.load("raocoin2");

Then, define a currency by 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):

local 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:

local 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.
ignoreHud boolean Determines whether or not the currency will display even when the HUD is hidden.
img LuaImageResource Contains the image holding the currency's UI element.
x number The x-coordinate in screen spaaaaaace of the upper-left corner of the UI element.
y number The y-coordinate in screen spaaaaaace 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. int
Currency:set value
Sets the currency value, but does not save it to the disk. nil int

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 int

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.

Events

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

Currency:onCollect increment item
Called when the currency counter is incremented. int

The amount the currency increased by. (Will always be 1 for NPC-based currencies)

NPC

The NPC that was collected when increasing the currency. (Will be nil for mem-currencies).


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 spaaaaaace or world spaaaaaace? Defaults to true (screen spaaaaaace).

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 spaaaaaace.

number

The y-coordinate of the bottom block in world spaaaaaace.

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 ignoreHud
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 spaaaaaace. Defaults to 0.

number:optional

The y-coordinate of the top-left corner of the UI object in screen spaaaaaace. 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.

boolean:optional

Should this currency display its UI element even when the HUD is not visible? Defaults to false.

registerMemCurrency address memtype restore showUI UIx UIy imgPath ignoreHud
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 spaaaaaace. Defaults to 0.

number:optional

The y-coordinate of the top-left corner of the UI object in screen spaaaaaace. 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.

boolean:optional

Should this currency display its UI element even when the HUD is not visible? Defaults to false.

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. Should only be used inside onHUDDraw, as using this in onLoop will give slight errors. table of number
worldToScreen x y
Converts the given world coordinates to screen coordinates. Should only be used inside onHUDDraw, as using this in onLoop will give slight errors. 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 increment item
Called when any currency counter is incremented. Currency

The currency whose counter increased.

number

The amount the currency increased by. (Will always be 1 for NPC-based currencies)

NPC

The NPC that was collected when increasing the currency. (Will be nil for mem-currencies).

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.