Creating an Item

Has this ever happened to you? You're making a shop, but then you realize you don't have any items to sell! Happens all the time, right? What do you mean there isn't a shop tutorial yet...?

Creating items mostly involves copy pasting, then changing a few values. It's not too hard, but it can be a bit tedious if you're making a large amount of them.

Basic Items

Let's say you want to make an item that does, well, nothing but take up inventory space. Just make a new Lua file in data/items.

Here's an example item. It's useless, but it's an item.

local item, super = Class(Item, "useless_item")

function item:init()
    super.init(self)

    -- Display name
    self.name = "Useless Item"
    -- Name displayed when used in battle (optional)
    self.use_name = nil

    -- Item type (item, key, weapon, armor)
    self.type = "item"
    -- Item icon (for equipment)
    self.icon = nil
    -- Whether this item is for the light world
    self.light = false

    -- Battle description
    self.effect = "Useless"
    -- Shop description
    self.shop = "Useless"
    -- Menu description
    self.description = "This item is useless"
    -- Light world check text
    self.check = "It's useless"

    -- Default shop price (sell price is halved)
    self.price = 0
    -- Whether the item can be sold
    self.can_sell = false

    -- Consumable target mode (ally, party, enemy, enemies, or none)
    self.target = "none"
    -- Where this item can be used (world, battle, all, or none)
    self.usable_in = "none"
end

return item

See, it's just changing a bunch of variables. But, what if we want it to do something? That's where self.target and self.usable_in come in.

self.target

self.target determines who the item can be used on. It can be one of the following:

• ally: you pick an ally to use the item on
• party: you use it on the entire party
• enemy: you pick an enemy to use the item on
• enemies: you use it on all enemies
• none: there's no target, you just use it

self.usable_in

self.usable_in determines where the item can be used. It can be one of the following:

• world: you can use it in the overworld
• battle: you can use it in battle
• all: you can use it anywhere
• none: you can't use it

Making it do something

Let's make it usable in the overworld. That's easy, just change self.usable_in to "world". We should also make you select an ally to use it on, so change self.target to "ally".

function item:onWorldUse(target)
    return false
end

This is the function that gets called when you use the item in the overworld. It takes one argument, target, which is the target you selected.

So uh, let's make it explode people. This is why I wanted the player to select a target.

function item:onWorldUse(target)
    local character = Game.world:getPartyCharacter(target)
    if character then
        character:explode()
    end
    return false
end

If you give yourself the item, then try to use it on someone, they explode! Perfect, right?

Oh, right - how do we give ourselves the item?

Giving items

There's a few different ways to give yourself items, like shops and chests! But most of the time you want to use the function Game.inventory:tryGiveItem(item) to give items from absolutely wherever you want.

This is an awesome function that, as it's name suggests, tries to give us an item, and handles not being able to. Just in case the player is hoarding 48 rotten teas already.

So, to give out this awesome item, we could run something like this from another piece of code, like a cutscene:

local success, result_text = Game.inventory:tryGiveItem("useless_item") -- This gives out our item to the player

cutscene:text(result_text) -- This displays the "You got the ..." and "ITEM was added to your STORAGE" texts or "You already have too many ITEMs" which are generated by us from tryGiveItem.

But wait! This isn't a cutscene tutorial... Surely there's an easier way to test out our item?

You're in luck! Because there's also a Debug Menu in Kristal. And it can give us items too.

Just press Shift + ` (On some keyboards it may be Shift + ~ instead). A KRISTAL DEBUG menu should then appear.

Look around the menu for the Give Item option - that's what we're looking for. Then search for useless_item and select it. You'll hear a noise, and the item should now be in your inventory!

Heal Items

Heal items are simple, just extend HealItem instead.

You'll want to set self.heal_amount to the amount you want the item to heal the user. And... that's the only difference. Neat.

Armor

Here's everything special in the white ribbon:

self.type = "armor"
self.icon = "ui/menu/icon/armor"
-- Equip bonuses (for weapons and armor)
self.bonuses = {
    defense = 2
}
-- Bonus name and icon (displayed in equip menu)
self.bonus_name = "Cuteness"
self.bonus_icon = "ui/menu/icon/up"

-- Equippable characters (default true for armors, false for weapons)
self.can_equip = {
    susie = false
}

Bonuses is a simple table, taking defense, magic and attack, all optional keys.

Weapons

Here's some code from the EverybodyWeapon, an unused weapon:

self.type = "weapon"
self.icon = nil

-- Equip bonuses (for weapons and armor)
self.bonuses = {
    attack  = 12,
    defense = 6,
    magic   = 8,
}

-- No special bonus
self.bonus_name = nil
self.bonus_icon = nil

-- Everyone can equip
self.can_equip = {}

Key Items

Code from the cell phone:

self.type = "key"

...Yep, that's all you need to do.

Reactions

When you use an item, or equip one, characters might react. This is done with the self.reactions table. Taking a look at the EverybodyWeapon again, we get:

-- Character reactions
self.reactions = {
    susie = "Uhhh... Ok.",
    ralsei = "A perfect fit!",
    noelle = "Wh... what is this?",
}