Imbion: Imbion moved page Custom Ground Item Actions to Tutorial:Custom Ground Item Actions

2025-10-16T15:45:19Z

Imbion moved page Custom Ground Item Actions to Tutorial:Custom Ground Item Actions

← Older revision	Revision as of 15:45, 16 October 2025
(No difference)

Trio at 04:28, 29 June 2023

2023-06-29T04:28:25Z

← Older revision		Revision as of 04:28, 29 June 2023
Line 6:		Line 6:

	== Eat Action ==		== Eat Action ==

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

Line 62:		Line 61:

	== Use Action ==		== Use Action ==

	Return back to Ground Use Actions for the Apple item		Return back to Ground Use Actions for the Apple item

Trio at 04:26, 29 June 2023

2023-06-29T04:26:51Z

← Older revision		Revision as of 04:26, 29 June 2023
Line 5:		Line 5:
	* 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.		* 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 ===		== Eat Action ==

	Begin by finding the Apple in the Items list and double-click on it.		Begin by finding the Apple in the Items list and double-click on it.
Line 61:		Line 61:
	If you check the Stats menu, you'll notice that your base Attack has increased!		If you check the Stats menu, you'll notice that your base Attack has increased!

	=== Use Action ===		== Use Action ==

	Return back to Ground Use Actions for the Apple item		Return back to Ground Use Actions for the Apple item
Line 126:		Line 126:
	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!		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 ===		== Notes ==
	This includes some important members variables in the [https://github.com/RogueCollab/RogueEssence/blob/b6eafc83063f603bdb470689e5918346ed097e2e/RogueEssence/Ground/GroundContext.cs#L5, GroundContext] class		This includes some important members variables in the [https://github.com/RogueCollab/RogueEssence/blob/b6eafc83063f603bdb470689e5918346ed097e2e/RogueEssence/Ground/GroundContext.cs#L5, GroundContext] class
	* context.Item - The current inventory being used ([https://github.com/RogueCollab/RogueEssence/blob/b6eafc83063f603bdb470689e5918346ed097e2e/RogueEssence/Dungeon/InvItem.cs#L11, InvItem])		* context.Item - The current inventory being used ([https://github.com/RogueCollab/RogueEssence/blob/b6eafc83063f603bdb470689e5918346ed097e2e/RogueEssence/Dungeon/InvItem.cs#L11, InvItem])

Trio: Created page with "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..."

2023-06-29T04:26:07Z

Created page with "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..."

New page

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.

[[File:CustomGroundAction_FindItem.png | frameless | 200px]]

You should see the following page below.

[[File:CustomGroundAction_AppleMain.png | frameless]]

Scroll down until you see "Ground Use Actions"

[[File:CustomGroundAction_GroundUseAction.png | frameless | 700px]]

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.

[[File:CustomGroundAction_AppleGroundEatAction.png | frameless | 300px]]

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

[[File:CustomGroundAction_AfterEatAction.png | frameless | 700px]]

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

[[File:CustomGroundAction_Eat.png | frameless]]

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

<pre>
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
</pre>

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

[[File:CustomGroundAction_EatResult.png | frameless]]

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

[[File:CustomGroundAction_AfterEatAction.png | frameless | 700px]]

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.

[[File:CustomGroundAction_AppleGroundUseAction.png | frameless | 300px]]

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

[[File:CustomGroundAction_Multiple.png | frameless | 700px]]

Let's define the logic for the AppleGroundUseAction.

In event_misc.lua, copy the following code:

<pre>
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
</pre>

One important thing to note is the line:

<pre>
context.CancelState.Cancel = true
</pre>

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!

[[File:CustomGroundAction_Use.png | frameless]]

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

[[File:CustomGroundAction_EnterTropicalPath.png | frameless]]

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

[[File:CustomGroundAction_TropicalPath.png | frameless]]

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 [https://github.com/RogueCollab/RogueEssence/blob/b6eafc83063f603bdb470689e5918346ed097e2e/RogueEssence/Ground/GroundContext.cs#L5, GroundContext] class
* context.Item - The current inventory being used ([https://github.com/RogueCollab/RogueEssence/blob/b6eafc83063f603bdb470689e5918346ed097e2e/RogueEssence/Dungeon/InvItem.cs#L11, InvItem])
* context.Owner - The current ground user that used the item ([https://github.com/RogueCollab/RogueEssence/blob/b6eafc83063f603bdb470689e5918346ed097e2e/RogueEssence/Ground/GroundChar.cs#L20, GroundChar])
* context.User - The party member that the item is going to apply its effect to ([https://github.com/RogueCollab/RogueEssence/blob/b6eafc83063f603bdb470689e5918346ed097e2e/RogueEssence/Dungeon/Characters/Character.cs#L18, Character])
* context.CancelState.Cancel - Whether the item is consumed or not ([https://github.com/RogueCollab/RogueEssence/blob/b6eafc83063f603bdb470689e5918346ed097e2e/RogueEssence/Dungeon/GameEffects/GameContext.cs#L5, AbortStatus])

[[Category:Modding Data]]

Tutorial:Custom Ground Item Actions - Revision history

Imbion: Imbion moved page Custom Ground Item Actions to Tutorial:Custom Ground Item Actions

Trio at 04:28, 29 June 2023

Trio at 04:26, 29 June 2023