Shops

Relevant files: shop.lua, shopkeeper.lua

Creating a Shop

Shops are another game state that are able to be made in Kristal. They can contain items to be bought, can be sold to, and can have a lot of customizable functionality as well. Shop files go in scripts/shops.

Shop files can be made by extending the global Shop object. A basic shop file looks something like this:

local ShopName, super = Class(Shop)

function ShopName:init()
  super:init(self)
  
  self.encounter_text = "* Welcome."

  self:registerItem("tensionbit")
  self:registerItem("manual", 1)
end

return ShopName

The following variables and functions can be used to set up a shop. Shops need a lot of strings and functions used to create all of its behavior, so the init() function for any shop will likely be very large.

encounter_text: Text that appears when you enter a shop.
shop_text: Text that appears whenever you return to the main menu of a shop.
leaving_text: Text that appears when you leave a shop.
buy_menu_text: Text that appears when you're in the BUY submenu.
buy_confirmation_text: Text that appears when asking for confirmation to buy something.
buy_refuse_text: Text that appears when you select "no" when confirming whether to buy something.
buy_text: Text that appears when you select "yes" when confirming whether to buy something.
buy_storage_text Text that appears when you buy something and it goes to storage.
buy_too_expensive_text: Text that appears when you attempt to buy something but can't afford it.
buy_no_space_text: Text that appears when you attempt to buy something but don't have enough space for it.
sell_menu_text: Text that appears when you're in the SELL submenu.
sell_no_price_text: Text that appears when you attempt to sell something that has no sell price.
sell_nothing_text: Text that appears when you attempt to sell an empty slot.
sell_confirmation_text: Text that appears when asking for confirmation to sell something.
sell_refuse_text: Text that appears when you select "no" when confirming whether to sell something.
sell_text: Text that appears when you select "yes" when confirming whether to sell something.
sell_no_storage_text: Text that appears when you have no items in a storage.
talk_text: Text that appears when you're in the TALK submenu.
sell_options_text: A table that can define strings for the fields item, weapon, armor, and pocket, which will define text that appears when you're in the SELL submenu for that type of item.
hide_storage_text: Whether the shop should display how much space you have in storages.
menu_options: A table of values defining what options you can select from the main menu of the shop. Each value should a table with 2 values; the first value in each of these tables is what text should be displayed, and the second value either a string defining what submenu it should send you to (see Shop States below for more detail), or a function to be called when the player selects that option.
items: A table of what items the shop offers. Should not be changed directly, see registerItem() below.
talks: A table of topics that can be selected in the TALK submenu. Should not be changed directly, see registerTalk() below.
talk_replacements: A table of topics that will replace other topics after they have been chosen. Should not be changed directly, see registerTalkAfter() below.
sell_options: A table of values defining what storages you can select from the SELL submenu. Each value should be a table with 2 values; the first value in each of these tables is what text should be displayed, and the second value is which storage should be used for selling.
background: A string referring to the file path of the texture to use for the shop, relative to assets/sprites.
background_sprite: The Sprite instance used for the background. Cannot be referenced in init().
shop_music: A string referring to the file path of the song to use for the shop, relative to assets/music.
music: The Music instance used for the shop.
state: The current state of the shop. Should not be changed directly, see setState() below.
state_reason: The current reason for the current state of the shop. Should not be changed directly, see setState() below.
timer: An instance of a Timer object.
shopkeeper: The Shopkeeper instance used for the shop. See Shopkeepers below for how to set one up.

setState(state, reason): Changes the shop's state. state is a string referring to the new state the shop should enter, and reason is an optional string providing more information if necessary. See Shop States below for more detail.
getState(): Returns the shop's current state.
leave(): Fades out the shop and exits it.
leaveImmediate(): Immediately exits the shop.
startDialogue(text, callback): Starts dialogue for the shop. text is either a string or a table of strings defining dialogue to be said, and callback is either a string, which will set the state of the shop to callback when the dialogue finishes, or a function, which will be called when the dialogue finishes. If callback is a function that returns true, the shop's state will not be reset when the dialogue finishes.
registerItem(item, amount, flag): Adds an item to be purchased from the shop. item is either a string referring to an item ID or an Item instaance, amount is an optional number defining how many of the item can be bought before the shop runs out, and flag is an optional string that, if defined, will override amount and set it to whatever value is returned by getFlag() for that string.
replaceItem(item, index, amount, flag): Replaces an item at the specified index with the specified item. item is either a string referring to an item ID or an Item instaance, index is a number defining what item slot in the shop should be replaced with this item, amount is an optional number defining how many of the item can be bought before the shop runs out, and flag is an optional string that, if defined, will override amount and set it to whatever value is returned by getFlag() for that string.
registerTalk(talk, color): Adds a topic that can be selected in the TALK submenu. talk is a string defining what text to be displayed and what will be passed into startTalk() (see Overridable Functions below), and color is an optional table of 3 or 4 values defining the RGB(A) of the topic text (defaulting to white).
replaceTalk(talk, index, color): Replaces the topic at the specified index with a new topic. talk is a string defining what text to be displayed and what will be passed into startTalk() (see Overridable Functions below), index is a number defining which topic to replace, and color is an optional table of 3 or 4 values defining the RGB(A) of the topic text, (defaulting to white).
registerTalkAfter(talk, index, flag, value, color): Defines a topic that will replace the topic at the specified index after that topic has been chosen. talk is the new topic name to be used, index is a number defining which topic will be replaced once selected, flag is an optional string that will be checked before replacing the topic if defined, only replacing the topic if the value returned by getFlag() for that string is true or equal to value if that is defined, and color is an optional table of 3 or 4 values defining the RGB(A) of the topic text (defaulting to yellow instead of white).
setFlag(name, value): Sets a save data flag for the shop to the specified value.
getFlag(name, default): Gets a save data flag for the shop, returning default if the flag doesn't exist.

Overridable Functions

Shops have several functions that can (and sometimes must) be overridden to define certain behavior. The following is a list of these functions:

onEnter(): Called when the shop is entered.
onLeave(): Called when the player leaves the shop. Responsible for starting dialogue with leaving_text and setting state to LEAVING.
onTalk() Called when the player enters the TALK submenu.
onEmote(emote): Called when dialogue text uses the emote DialogueText modifier. emote is a string referring to the argument provided by the modifier. Responsible for calling onEmote() for the shopkeeper.
startTalk(topic): Called when the player selects a topic in the TALK submenu. topic is a string referring to the topic selected. This function is where you should start dialogue based on what topic is selected. See the example mod's shop for an example of how this function should be used.
onStateChange(old, new): Called whenever the shop changes state. old is a string referring to the previous state, and new is a string referring to the newly set state. See Shop States below for more detail.

Shop States

All functionality in shops is separated by "states", to define what should be happening and what the player's input should do. Each state is defined by a string.

The following is a list of all states used by the shop, as well as a description of what they do, and what information they may need (provided by the reason argument in Shop:setState()). The available states are:

MAINMENU: Used when the player is in the main menu of the shop, before they have entered any submenus such as talking or buying.
BUYMENU: Used when the player is in the buy menu of the shop, selecting items to purchase.
SELLMENU: Used when the player is selecting a storage to sell items from.
SELLING: Used when the player is in the sell menu of the shop, selecting items to sell. state_reason will be the name of the storage being sold from.
TALKMENU: Used when the player is in the talk menu of the shop, selecting a topic.
DIALOGUE: Used when dialogue is occurring.
LEAVE: Used to leave the shop.
LEAVING: Used while the shop is fading out.

Shopkeepers

A shop's shopkeeper variable is set to a new instance of the global Shopkeeper object upon initiation. This variable can be used to create a shopkeeper actor that will be used in dialogue.

The following are variables and functions that can be set for the Shopkeeper:

slide: Whether the shopkeeper should slide out of the way of the buy menu when the player enters it.
talk_sprite: A boolean determining whether the shopkeeper should animate when talking.
actor: The Actor instance used by the shopkeeper. Should not be set directly, see setActor() below.
sprite: The ActorSprite instance used by the shopkeeper. Should not be set directly, see setActor() below.

setActor(actor): Sets the actor and sprite for the shopkeeper. actor is either a string referring to an actor ID or an Actor instance. Automatically sets the sprite's scale to 2, and its origin to 0.5, 1.
getActor(): Returns the Actor instance used by the shopkeeper.
setSprite(sprite): Sets the sprite for the shopkeeper. sprite is a string referring to the file path of an image, relative to assets/sprites.
setAnimation(animation): Sets the animation for the shopkeeper. animation is a string referring to an animation ID defined by the shopkeeper's actor.
onEmote(emote): Sets the sprite for the shopkeeper's actor. emote is a string referring to either a file path of an image or an animation ID.