Custom Ground Item Actions

In this tutorial, we'll create our own custom ground actions for currently existing items. This tutorial will cover writing your own custom Lua GroundItemScript. Make your game is set to a mod in Modding Intro so that you’re editing a mod instead of the base game.

We want add the following custom ground actions to the Apple:

• Eat: The player gains an attack stat boost after it is consumed.
• Use: The player is a prompted whether or not they want to enter Tropical Path. The item is consumed only if the player answers Yes.

Eat Action

Begin by finding the Apple in the Items list and double-click on it.

You should see the following page below.

Scroll down until you see "Ground Use Actions"

Click on [Add]. Then do the following:

• Set the Type to be ScriptItemEvent.
• Set the Script to be AppleGroundEatAction. We will later code the logic for this event.
• Set the "Ground Usage Type" to be Eat. This will set the menu action name to be Eat when using the item.
• Set the Selection to be Others. This allows the player to choose which party member the item will effect.

Click on [OK] and then save. You should see a new event added to "Ground Use Actions"!

If you spawn in an Apple and attempt to Eat, nothings happens. We need to code the logic for our Eat event!

Create a file called "event_misc.lua" in "PMDO/MODS/{MOD_NAME}/SCRIPT". And copy the code below into the file.

GROUND_ITEM_EVENT_SCRIPT = {}

function GROUND_ITEM_EVENT_SCRIPT.AppleGroundEatAction(context)
  local player = context.User
  local prevStat = player.BaseAtk
  player.AtkBonus = player.AtkBonus + 1
  local newStat = player.BaseAtk

  local player_name = player:GetDisplayName(false)
  local stat_diff = newStat - prevStat
  local msg = player_name .. "'s base Attack was boosted by " .. stat_diff .. "."

  UI:ResetSpeaker()
  UI:WaitShowDialogue(msg)
end

Reload the scripts through the Dev Menu and attempt to Eat the Apple again! You should now see similar results below.

If you check the Stats menu, you'll notice that your base Attack has increased!

Use Action

Return back to Ground Use Actions for the Apple item

Click on [Add] and do the following:

• Set the Type to be ScriptItemEvent.
• Set the Script to be AppleGroundUseAction.
• Set the "Ground Usage Type" to be Use.
• Set the Selection to be Self.

Click on [OK] and save. You will now see two items under "Ground Use Actions".

Let's define the logic for the AppleGroundUseAction.

In event_misc.lua, copy the following code:

function GROUND_ITEM_EVENT_SCRIPT.AppleGroundUseAction(context)
  UI:ResetSpeaker()
  local zone = _DATA.DataIndices[RogueEssence.Data.DataManager.DataType.Zone]:Get('tropical_path')
  UI:ChoiceMenuYesNo(STRINGS:FormatKey("DLG_ASK_ENTER_DUNGEON", zone:GetColoredName()), false)
  UI:WaitForChoice()
  ch = UI:ChoiceResult()
  if ch then
    _DATA:PreLoadZone('tropical_path')
    SOUND:PlayBGM("", true)
    GAME:FadeOut(false, 20)
    GAME:EnterDungeon('tropical_path', 0, 0, 0, RogueEssence.Data.GameProgress.DungeonStakes.Risk, true, true)
  else
    context.CancelState.Cancel = true
  end
end

One important thing to note is the line:

context.CancelState.Cancel = true

By default CancelState.Cancel is set to false. But by setting it to true, the item isn't consumed in the inventory if the player chooses No.

If you spawn in an Apple again, you'll notice that Use has been added to the list of menu actions!

If you attempt to Use the Apple, you'll see the following prompt below:

Clicking on [Yes] will consume the Apple in the inventory and transport you to Tropical Path.

But clicking [No] will not consume the Apple and keep you in the same area.

This concludes adding your own custom ground actions to items! You learned how to mod existing items to have ground actions and wrote a custom Lua item script!

Notes

This includes some important members variables in the GroundContext class

• context.Item - The current inventory being used (InvItem)
• context.Owner - The current ground user that used the item (GroundChar)
• context.User - The party member that the item is going to apply its effect to (Character)
• context.CancelState.Cancel - Whether the item is consumed or not (AbortStatus)