PMDOWiki - User contributions [en]

SingleEvent Scripts

2024-03-13T21:52:04Z

Palika:

These events go into the <code>event_single.lua</code> file of your mod. As of version v0.7.25, you will need to copy this file from base PMDO into your mod first, then paste these scripts into it.

== Custom Boss Fight Win Conditions / End effects: ==
:'''Author:''' Palika

Want to have it so a boss fight has an alternative win condition than just "beat all enemies"? Want something special to happen when that win condition is met? If the answer is yes, you'll need to override the usual BeginBattleEvent and its corresponding CheckBossClearEvent and end_sequence responsible for these features with the Lua version.

=== Code ===
<pre>
---
-- Reimplementation of Audino's C# event for BeginBattleEvent.
-- This will allow us to inject custom function code before ending a battle
-- (such as clearing existing lava flows when a boss fight ends).
-- @tparam GameEventOwner owner
-- @tparam Character ownerChar
-- @tparam SingleCharContext context
-- @tparam table args Table of format {CustomClearEvent="NameOfFunctionThatRunsOnClear", [other arguments to said script]}
function SINGLE_CHAR_SCRIPT.LuaBeginBattleEvent(owner, ownerChar, context, args)
local MapCheckState = luanet.import_type('RogueEssence.Dungeon.MapCheckState')
local SingleCharScriptEvent = luanet.import_type('RogueEssence.Dungeon.SingleCharScriptEvent')

local map_clear_idx = 'map_clear_check'

if context.User ~= nil then return end
--if a custom clear event is not given, use the default one.
if args.CustomClearEvent == nil then args.CustomClearEvent = 'LuaCheckBossClearEvent' end

--Turn on Team Mode if allowed when the boss fight starts.
if _DUNGEON:CanUseTeamMode() then
_DUNGEON:SetTeamMode(true)
end

local clear_status = RogueEssence.Dungeon.MapStatus(map_clear_idx)
clear_status:LoadFromData()

local check = clear_status.StatusStates:GetWithDefault(luanet.ctype(MapCheckState))
--The 2nd argument in the function below needs a string that represents a lua table of the arguments to pass. Serpent.line will convert the lua table to a string representing it for us.
--We only NEED to pass args, as owner, ownerchar, and context are automatically passed in when the check event is called
check.CheckEvents:Add(SingleCharScriptEvent(args.CustomClearEvent, Serpent.line(args)))
--check.CheckEvents:Add(LuaCheckBossClearEvent(owner, ownerChar, context, args))

TASK:WaitTask(_DUNGEON:AddMapStatus(clear_status))
end

--Import Serpent library.
Serpent = require 'lib.serpent'

---
-- Reimplementation of the basic CheckBossClearEvent.
-- Call something different from LuaBeginBattleEvent or edit this accordingly if you
-- want a different wincon for your map or special effects/anims on win.
-- @tparam GameEventOwner owner
-- @tparam Character ownerChar Not used by this function.
-- @tparam SingleCharContext context Not used by this function.
-- @tparam table args Table of caller-defined arguments. Not used by this function.
function SINGLE_CHAR_SCRIPT.LuaCheckBossClearEvent(owner, ownerChar, context, args)
local MapCheckState = luanet.import_type('RogueEssence.Dungeon.MapCheckState')
local SingleCharScriptEvent = luanet.import_type('RogueEssence.Dungeon.SingleCharScriptEvent')

---
-- Sequence that runs when map is over. Fade out, cut the music, etc.
-- @usage Coroutine
function end_sequence()
_GAME:BGM("", true)

TASK:WaitTask(_GAME:FadeOut(false))

_DUNGEON:ResetTurns()

-- restore all and remove all map status
local statuses_to_remove = {}
for i = 0, _ZONE.CurrentMap.Status.Keys.Count - 1, 1 do
statuses_to_remove[i] = _ZONE.CurrentMap.Status.Keys[i]
end

for i = 0, #statuses_to_remove - 1, 1 do
TASK:WaitTask(_DUNGEON:RemoveMapStatus(statuses_to_remove[i], false))
end

-- heal everyone in the party
for i = 0, GAME:GetPlayerPartyCount() - 1, 1 do
_DATA.Save.ActiveTeam.Players[i]:FullRestore()
end

TASK:WaitTask(_GAME:EndSegment(RogueEssence.Data.GameProgress.ResultType.Cleared))

end

-- For each enemy team, check each chara in that team.
-- If any are still alive, then fail this check and return early.
for i = 0, _ZONE.CurrentMap.MapTeams.Count - 1, 1 do
local team = _ZONE.CurrentMap.MapTeams[i].Players
for j = 0, team.Count - 1, 1 do
-- Break and return early if even one enemy is not dead.
if not team[j].Dead then return end
end
end

-- Everyone's dead, clear the scene.
local checks = owner.StatusStates:GetWithDefault(luanet.ctype(MapCheckState))

-- The call originally for this was to remove(this), which isn't in lua.
-- So we need to find the LuaCheckBossClearEvent and remove that (remove ourself)
for i = 0, checks.CheckEvents.Count - 1, 1 do
if LUA_ENGINE:TypeOf(checks.CheckEvents[i]) == luanet.ctype(SingleCharScriptEvent) then
if checks.CheckEvents[i].Script == args.CustomClearEvent then
checks.CheckEvents:Remove(checks.CheckEvents[i])
end
end
end

if _DATA.CurrentReplay == nil then
TASK:WaitTask(end_sequence())
else
TASK:WaitTask(_GAME:EndSegment(RogueEssence.Data.GameProgress.ResultType.Cleared))
end

end
</pre>

=== Usage ===

The first function, <code>LuaBeginBattleEvent</code>, is responsible for letting PMDO know to look at <code>LuaCheckBossClearEvent</code> to determine when the map is won. Instead of the usual <code>BeginBattleEvent</code> in your boss fight's OnMapStart's Map Effects, you need to call a SingleCharScriptEvent for LuaBeginBattleEvent instead. It'll look like this:

[[File:LuaBeginBattleEvent.PNG]]

<code>LuaCheckBossClearEvent</code> is responsible for identifying when the map is won, and then the <code>end_sequence</code> function within it is responsible for fading stuff out and actually winning the map.

You won't need to modify the scripting for LuaBeginBattleEvent at all; it should remain as it is.

==== Tutorial: Alternate win condition ====
If you would like an alternate win condition or end sequence besides just fading out, then you will need to edit <code>LuaCheckBossClearEvent</code> and its <code>end_sequence</code> respectively.

# First, copy and rename your custom version of <code>LuaCheckBossClearEvent</code> to something more appropriately fitting.
#* Let's say we want a win condition where you only have to defeat the leader of a gang to win the boss fight. We'll call this function instead <code>CheckDefeatedGangLeader</code>. Copy the <code>LuaCheckBossClearEvent</code> function above and rename it to <code>CheckDefeatedGangLeader</code>.
# In <code>LuaBeginBattleEvent</code>, be sure to pass an argument of <code>CustomClearEvent = 'CheckDefeatedGangLeader'</code> when you define it in the MapEffects, so <code>LuaBeginBattleEvent</code> will knows to use your custom function instead of the default one given. This is done in the Arg Table in the picture above. The value there should look something like {CustomClearEvent = 'CheckDefeatedGangLeader'}.
# Next, you need to modify how <code>CheckDefeatedGangLeader</code> identifies the win condition. If the win condition is failed, the function should return early. The default one does this by checking all enemy teams, and if any members on any team are not dead, then that means an enemy is still alive and the win condition has failed.
#* For our example, if our gang leader is a Scrafty, we should iterate through all enemy teams and see if we find a member that is both a Scrafty and alive. If so, then our win condition has failed and we should return early.
#* Alternatively, you can assign a LuaTable property to the Scrafty that marks it as, say, <code>.GangLeader = true</code>, and make sure that there are no NPCs with a LuaTable property of 'GangLeader' equal to true that are alive. Doing it like this would allow you to have as many GangLeaders as you may want that need to be defeated to meet the win condition.
# With all this done, when the Scrafty is defeated, the map should end and call <code>end_sequence()</code> as long as we aren't watching a replay. <code>end_sequence()</code> is responsible for fading the map and music out.
#* You can redefine it to anything you want if you want different things to happen when you actually win. For example, maybe you want your party members to face the camera and do a pose for a few seconds before the game fades out. You could accomplish this by writing code at the very top of end_sequence that makes all your party members do the face down and do the Pose animation!
#* You can do anything of course, but be careful not to remove things that may be important to handling the end of the dungeon adventure, such as the line of code responsible for ending the segment as Cleared.

== Causing a Wipe if allies faint: ==

Want to cause a party wipe in the event that a specific character faints? Perhaps the Hero/Partner characters? This is easily achievable again via pre-made Lua scripting to be placed within event_single.lua.

We'll start by setting up the functionality. Place the following code within event_single.lua:

--Check to make sure nobody marked as "IsPartner" is dead. Check guests as well
--if one is dead, then cause an instant game over
--if someone died and they aren't "IsPartner", then send them home automatically.
function SINGLE_CHAR_SCRIPT.AllyDeathCheck(owner, ownerChar, context, args)
local player_count = GAME:GetPlayerPartyCount()
local guest_count = GAME:GetPlayerGuestCount()
if player_count < 1 then return end--If there's no party members then we dont need to do anything
for i = 0, player_count - 1, 1 do
local player = GAME:GetPlayerPartyMember(i)
if player.Dead and player.IsPartner then --someone died
for j = 0, player_count - 1, 1 do --beam everyone else out
player = GAME:GetPlayerPartyMember(j)
if not player.Dead then--dont beam out whoever died
--delay between beam outs
GAME:WaitFrames(60)
TASK:WaitTask(_DUNGEON:ProcessBattleFX(player, player, _DATA.SendHomeFX))
player.Dead = true
end
end
--beam out guests
for j = 0, guest_count - 1, 1 do --beam everyone else out
guest = GAME:GetPlayerGuestMember(j)
if not guest.Dead then--dont beam out whoever died
--delay between beam outs
GAME:WaitFrames(60)
TASK:WaitTask(_DUNGEON:ProcessBattleFX(guest, guest, _DATA.SendHomeFX))
guest.Dead = true
end
end
return--cut the script short here if someone died, no need to check guests
end
end

--check guests as well
if guest_count < 1 then return end--If there's no guest members then we dont need to do anything
for i = 0, guest_count - 1, 1 do
local guest = GAME:GetPlayerGuestMember(i)
if guest.Dead and guest.IsPartner then --someone died
--beam player's team out first
for j = 0, player_count - 1, 1 do --beam everyone else out
player = GAME:GetPlayerPartyMember(j)
if not player.Dead then--dont beam out whoever died
TASK:WaitTask(_DUNGEON:ProcessBattleFX(player, player, _DATA.SendHomeFX))
player.Dead = true
GAME:WaitFrames(60)
end
end
for j = 0, guest_count - 1, 1 do --beam everyone else out
guest = GAME:GetPlayerGuestMember(j)
if not guest.Dead then--dont beam out whoever died
TASK:WaitTask(_DUNGEON:ProcessBattleFX(guest, guest, _DATA.SendHomeFX))
guest.Dead = true
GAME:WaitFrames(60)
end
end
end
end

end

Once this code is in place, we need to set up Universal to call this code On Deaths. In the Dev menu, go to the Constants tab, click Universal, and scroll down to On Deaths. Expand the section there, and click Add. We'll add a SingleCharScriptEvent for AllyDeathCheck here. Once you do that, make sure you set the priority for this event to 10. This will make it so the AllyDeathCheck code we put in event_single.lua earlier will run whenever someone dies at the right timing relative to other scripts. Your config should look something like this after:

[[File:AllyDeathUniversal.PNG]]

You're all set now! There's only one more thing you need to do. The script we put only actually checks to see if characters marked as "IsPartner" are dead. IsPartner does not literally mean they are a partner; it is an attribute of Pokémon on your team you can set via scripting that determine whether they can leave the party or not, so it's important to give, say, the Hero character this attribute as well. However, the script code from earlier also uses that flag to determine if the character causes a party wipe upon their death. So be sure in your scripts to mark any important party members IsPartner flag to true if you want them to cause a wipe. You can, of course, change the code of the code above to check for other things instead if you want other attributes to be relevant for a party member death to cause a wipe, but IsPartner Pokémon is the most common kind of teammate you'd want to cause a wipe if they faint.

An example of setting isPartner. This would set the character in the first slot of your partner to not be removable from your team, and cause a wipe with the code from earlier if they faint.:
GAME:GetPlayerPartyMember(0).IsPartner = true

== Giving Exclamation points to low health allies ==

Want that cool little effect where characters low on HP have an exclamation point over their head? Using some pre-configured event_single Lua code and by configuring your own Critical Health status, you can achieve this cosmetic effect pretty easily.

First, let's configure the status effect that'll give the player the exclamation point over their head. Go to the Data tab on the Dev menu, then go to Statuses. Click the Add button on the menu that pops up, and it's here we'll configure our Critical Health status. Configure yours to match what you see in the image below. Anything you don't see in the window in this image can be left as the defaults.

[[File:CriticalHealthStatus.PNG]]

Next, insert this code into your event_single.lua file for your mod.

Code:
function SINGLE_CHAR_SCRIPT.SetCriticalHealthStatus(owner, ownerChar, context, args)
local player_count = GAME:GetPlayerPartyCount()
local critical = RogueEssence.Dungeon.StatusEffect("critical_health")
--initialize status data before adding it to anything
critical:LoadFromData()
for i = 0, player_count - 1, 1 do
local player = GAME:GetPlayerPartyMember(i)
if player.HP <= player.MaxHP / 4 and player:GetStatusEffect("critical_health") == nil then
TASK:WaitTask(player:AddStatusEffect(nil, critical, false))
elseif player.HP > player.MaxHP / 4 and player:GetStatusEffect("critical_health") ~= nil then
TASK:WaitTask(player:RemoveStatusEffect("critical_health"))
end
end
end

Once you've done that, we need to configure Universal to run this code at the end of turns. Click the Constants tab on the Dev menu, go to Universal, and scroll down until you find "On Turn Ends". Here, we'll add a SingleCharScriptEvent that calls SetCriticalHealthStatus on the end of turns, so the Critical Health status that displays the exclamation point is set or removed when someone's HP passes the 1/4 HP threshold. Your configuration should look like this in the end:

[[File:LowHealthExclamation.PNG]]

You should be all set! Your ally team members (not guests, you can expand this functionality yourself if you so wish to cover guests) will get an exclamation above their head and an informative status when they're low on HP.

[[File:LowHP.PNG]]

SingleEvent Scripts

2024-03-13T21:41:54Z

Palika:

These events go into the <code>event_single.lua</code> file of your mod. As of version v0.7.25, you will need to copy this file from base PMDO into your mod first, then paste these scripts into it.

== Custom Boss Fight Win Conditions / End effects: ==
:'''Author:''' Palika

Want to have it so a boss fight has an alternative win condition than just "beat all enemies"? Want something special to happen when that win condition is met? If the answer is yes, you'll need to override the usual BeginBattleEvent and its corresponding CheckBossClearEvent and end_sequence responsible for these features with the Lua version.

=== Code ===
<pre>
---
-- Reimplementation of Audino's C# event for BeginBattleEvent.
-- This will allow us to inject custom function code before ending a battle
-- (such as clearing existing lava flows when a boss fight ends).
-- @tparam GameEventOwner owner
-- @tparam Character ownerChar
-- @tparam SingleCharContext context
-- @tparam table args Table of format {CustomClearEvent="NameOfFunctionThatRunsOnClear", [other arguments to said script]}
function SINGLE_CHAR_SCRIPT.LuaBeginBattleEvent(owner, ownerChar, context, args)
local MapCheckState = luanet.import_type('RogueEssence.Dungeon.MapCheckState')
local SingleCharScriptEvent = luanet.import_type('RogueEssence.Dungeon.SingleCharScriptEvent')

local map_clear_idx = 'map_clear_check'

if context.User ~= nil then return end
--if a custom clear event is not given, use the default one.
if args.CustomClearEvent == nil then args.CustomClearEvent = 'LuaCheckBossClearEvent' end

--Turn on Team Mode if allowed when the boss fight starts.
if _DUNGEON:CanUseTeamMode() then
_DUNGEON:SetTeamMode(true)
end

local clear_status = RogueEssence.Dungeon.MapStatus(map_clear_idx)
clear_status:LoadFromData()

local check = clear_status.StatusStates:GetWithDefault(luanet.ctype(MapCheckState))
--The 2nd argument in the function below needs a string that represents a lua table of the arguments to pass. Serpent.line will convert the lua table to a string representing it for us.
--We only NEED to pass args, as owner, ownerchar, and context are automatically passed in when the check event is called
check.CheckEvents:Add(SingleCharScriptEvent(args.CustomClearEvent, Serpent.line(args)))
--check.CheckEvents:Add(LuaCheckBossClearEvent(owner, ownerChar, context, args))

TASK:WaitTask(_DUNGEON:AddMapStatus(clear_status))
end

--Import Serpent library.
Serpent = require 'lib.serpent'

---
-- Reimplementation of the basic CheckBossClearEvent.
-- Call something different from LuaBeginBattleEvent or edit this accordingly if you
-- want a different wincon for your map or special effects/anims on win.
-- @tparam GameEventOwner owner
-- @tparam Character ownerChar Not used by this function.
-- @tparam SingleCharContext context Not used by this function.
-- @tparam table args Table of caller-defined arguments. Not used by this function.
function SINGLE_CHAR_SCRIPT.LuaCheckBossClearEvent(owner, ownerChar, context, args)
local MapCheckState = luanet.import_type('RogueEssence.Dungeon.MapCheckState')
local SingleCharScriptEvent = luanet.import_type('RogueEssence.Dungeon.SingleCharScriptEvent')

---
-- Sequence that runs when map is over. Fade out, cut the music, etc.
-- @usage Coroutine
function end_sequence()
_GAME:BGM("", true)

TASK:WaitTask(_GAME:FadeOut(false))

_DUNGEON:ResetTurns()

-- restore all and remove all map status
local statuses_to_remove = {}
for i = 0, _ZONE.CurrentMap.Status.Keys.Count - 1, 1 do
statuses_to_remove[i] = _ZONE.CurrentMap.Status.Keys[i]
end

for i = 0, #statuses_to_remove - 1, 1 do
TASK:WaitTask(_DUNGEON:RemoveMapStatus(statuses_to_remove[i], false))
end

-- heal everyone in the party
for i = 0, GAME:GetPlayerPartyCount() - 1, 1 do
_DATA.Save.ActiveTeam.Players[i]:FullRestore()
end

TASK:WaitTask(_GAME:EndSegment(RogueEssence.Data.GameProgress.ResultType.Cleared))

end

-- For each enemy team, check each chara in that team.
-- If any are still alive, then fail this check and return early.
for i = 0, _ZONE.CurrentMap.MapTeams.Count - 1, 1 do
local team = _ZONE.CurrentMap.MapTeams[i].Players
for j = 0, team.Count - 1, 1 do
-- Break and return early if even one enemy is not dead.
if not team[j].Dead then return end
end
end

-- Everyone's dead, clear the scene.
local checks = owner.StatusStates:GetWithDefault(luanet.ctype(MapCheckState))

-- The call originally for this was to remove(this), which isn't in lua.
-- So we need to find the LuaCheckBossClearEvent and remove that (remove ourself)
for i = 0, checks.CheckEvents.Count - 1, 1 do
if LUA_ENGINE:TypeOf(checks.CheckEvents[i]) == luanet.ctype(SingleCharScriptEvent) then
if checks.CheckEvents[i].Script == args.CustomClearEvent then
checks.CheckEvents:Remove(checks.CheckEvents[i])
end
end
end

if _DATA.CurrentReplay == nil then
TASK:WaitTask(end_sequence())
else
TASK:WaitTask(_GAME:EndSegment(RogueEssence.Data.GameProgress.ResultType.Cleared))
end

end
</pre>

=== Usage ===

The first function, <code>LuaBeginBattleEvent</code>, is responsible for letting PMDO know to look at <code>LuaCheckBossClearEvent</code> to determine when the map is won. Instead of the usual <code>BeginBattleEvent</code> in your boss fight's OnMapStart's Map Effects, you need to call a SingleCharScriptEvent for LuaBeginBattleEvent instead. It'll look like this:

[[File:LuaBeginBattleEvent.PNG]]

<code>LuaCheckBossClearEvent</code> is responsible for identifying when the map is won, and then the <code>end_sequence</code> function within it is responsible for fading stuff out and actually winning the map.

You won't need to modify the scripting for LuaBeginBattleEvent at all; it should remain as it is.

==== Tutorial: Alternate win condition ====
If you would like an alternate win condition or end sequence besides just fading out, then you will need to edit <code>LuaCheckBossClearEvent</code> and its <code>end_sequence</code> respectively.

# First, copy and rename your custom version of <code>LuaCheckBossClearEvent</code> to something more appropriately fitting.
#* Let's say we want a win condition where you only have to defeat the leader of a gang to win the boss fight. We'll call this function instead <code>CheckDefeatedGangLeader</code>. Copy the <code>LuaCheckBossClearEvent</code> function above and rename it to <code>CheckDefeatedGangLeader</code>.
# In <code>LuaBeginBattleEvent</code>, be sure to pass an argument of <code>CustomClearEvent = 'CheckDefeatedGangLeader'</code> when you define it in the MapEffects, so <code>LuaBeginBattleEvent</code> will knows to use your custom function instead of the default one given.
# Next, you need to modify how <code>CheckDefeatedGangLeader</code> identifies the win condition. If the win condition is failed, the function should return early. The default one does this by checking all enemy teams, and if any members on any team are not dead, then that means an enemy is still alive and the win condition has failed.
#* For our example, if our gang leader is a Scrafty, we should iterate through all enemy teams and see if we find a member that is both a Scrafty and alive. If so, then our win condition has failed and we should return early.
#* Alternatively, you can assign a LuaTable property to the Scrafty that marks it as, say, <code>.GangLeader = true</code>, and make sure that there are no NPCs with a LuaTable property of 'GangLeader' equal to true that are alive. Doing it like this would allow you to have as many GangLeaders as you may want that need to be defeated to meet the win condition.
# With all this done, when the Scrafty is defeated, the map should end and call <code>end_sequence()</code> as long as we aren't watching a replay. <code>end_sequence()</code> is responsible for fading the map and music out.
#* You can redefine it to anything you want if you want different things to happen when you actually win. For example, maybe you want your party members to face the camera and do a pose for a few seconds before the game fades out. You could accomplish this by writing code at the very top of end_sequence that makes all your party members do the face down and do the Pose animation!
#* You can do anything of course, but be careful not to remove things that may be important to handling the end of the dungeon adventure, such as the line of code responsible for ending the segment as Cleared.

== Causing a Wipe if allies faint: ==

Want to cause a party wipe in the event that a specific character faints? Perhaps the Hero/Partner characters? This is easily achievable again via pre-made Lua scripting to be placed within event_single.lua.

We'll start by setting up the functionality. Place the following code within event_single.lua:

--Check to make sure nobody marked as "IsPartner" is dead. Check guests as well
--if one is dead, then cause an instant game over
--if someone died and they aren't "IsPartner", then send them home automatically.
function SINGLE_CHAR_SCRIPT.AllyDeathCheck(owner, ownerChar, context, args)
local player_count = GAME:GetPlayerPartyCount()
local guest_count = GAME:GetPlayerGuestCount()
if player_count < 1 then return end--If there's no party members then we dont need to do anything
for i = 0, player_count - 1, 1 do
local player = GAME:GetPlayerPartyMember(i)
if player.Dead and player.IsPartner then --someone died
for j = 0, player_count - 1, 1 do --beam everyone else out
player = GAME:GetPlayerPartyMember(j)
if not player.Dead then--dont beam out whoever died
--delay between beam outs
GAME:WaitFrames(60)
TASK:WaitTask(_DUNGEON:ProcessBattleFX(player, player, _DATA.SendHomeFX))
player.Dead = true
end
end
--beam out guests
for j = 0, guest_count - 1, 1 do --beam everyone else out
guest = GAME:GetPlayerGuestMember(j)
if not guest.Dead then--dont beam out whoever died
--delay between beam outs
GAME:WaitFrames(60)
TASK:WaitTask(_DUNGEON:ProcessBattleFX(guest, guest, _DATA.SendHomeFX))
guest.Dead = true
end
end
return--cut the script short here if someone died, no need to check guests
end
end

--check guests as well
if guest_count < 1 then return end--If there's no guest members then we dont need to do anything
for i = 0, guest_count - 1, 1 do
local guest = GAME:GetPlayerGuestMember(i)
if guest.Dead and guest.IsPartner then --someone died
--beam player's team out first
for j = 0, player_count - 1, 1 do --beam everyone else out
player = GAME:GetPlayerPartyMember(j)
if not player.Dead then--dont beam out whoever died
TASK:WaitTask(_DUNGEON:ProcessBattleFX(player, player, _DATA.SendHomeFX))
player.Dead = true
GAME:WaitFrames(60)
end
end
for j = 0, guest_count - 1, 1 do --beam everyone else out
guest = GAME:GetPlayerGuestMember(j)
if not guest.Dead then--dont beam out whoever died
TASK:WaitTask(_DUNGEON:ProcessBattleFX(guest, guest, _DATA.SendHomeFX))
guest.Dead = true
GAME:WaitFrames(60)
end
end
end
end

end

Once this code is in place, we need to set up Universal to call this code On Deaths. In the Dev menu, go to the Constants tab, click Universal, and scroll down to On Deaths. Expand the section there, and click Add. We'll add a SingleCharScriptEvent for AllyDeathCheck here. Once you do that, make sure you set the priority for this event to 10. This will make it so the AllyDeathCheck code we put in event_single.lua earlier will run whenever someone dies at the right timing relative to other scripts. Your config should look something like this after:

[[File:AllyDeathUniversal.PNG]]

You're all set now! There's only one more thing you need to do. The script we put only actually checks to see if characters marked as "IsPartner" are dead. IsPartner does not literally mean they are a partner; it is an attribute of Pokémon on your team you can set via scripting that determine whether they can leave the party or not, so it's important to give, say, the Hero character this attribute as well. However, the script code from earlier also uses that flag to determine if the character causes a party wipe upon their death. So be sure in your scripts to mark any important party members IsPartner flag to true if you want them to cause a wipe. You can, of course, change the code of the code above to check for other things instead if you want other attributes to be relevant for a party member death to cause a wipe, but IsPartner Pokémon is the most common kind of teammate you'd want to cause a wipe if they faint.

An example of setting isPartner. This would set the character in the first slot of your partner to not be removable from your team, and cause a wipe with the code from earlier if they faint.:
GAME:GetPlayerPartyMember(0).IsPartner = true

== Giving Exclamation points to low health allies ==

Want that cool little effect where characters low on HP have an exclamation point over their head? Using some pre-configured event_single Lua code and by configuring your own Critical Health status, you can achieve this cosmetic effect pretty easily.

First, let's configure the status effect that'll give the player the exclamation point over their head. Go to the Data tab on the Dev menu, then go to Statuses. Click the Add button on the menu that pops up, and it's here we'll configure our Critical Health status. Configure yours to match what you see in the image below. Anything you don't see in the window in this image can be left as the defaults.

[[File:CriticalHealthStatus.PNG]]

Next, insert this code into your event_single.lua file for your mod.

Code:
function SINGLE_CHAR_SCRIPT.SetCriticalHealthStatus(owner, ownerChar, context, args)
local player_count = GAME:GetPlayerPartyCount()
local critical = RogueEssence.Dungeon.StatusEffect("critical_health")
--initialize status data before adding it to anything
critical:LoadFromData()
for i = 0, player_count - 1, 1 do
local player = GAME:GetPlayerPartyMember(i)
if player.HP <= player.MaxHP / 4 and player:GetStatusEffect("critical_health") == nil then
TASK:WaitTask(player:AddStatusEffect(nil, critical, false))
elseif player.HP > player.MaxHP / 4 and player:GetStatusEffect("critical_health") ~= nil then
TASK:WaitTask(player:RemoveStatusEffect("critical_health"))
end
end
end

Once you've done that, we need to configure Universal to run this code at the end of turns. Click the Constants tab on the Dev menu, go to Universal, and scroll down until you find "On Turn Ends". Here, we'll add a SingleCharScriptEvent that calls SetCriticalHealthStatus on the end of turns, so the Critical Health status that displays the exclamation point is set or removed when someone's HP passes the 1/4 HP threshold. Your configuration should look like this in the end:

[[File:LowHealthExclamation.PNG]]

You should be all set! Your ally team members (not guests, you can expand this functionality yourself if you so wish to cover guests) will get an exclamation above their head and an informative status when they're low on HP.

[[File:LowHP.PNG]]

File:AllyDeathUniversal.PNG

2024-03-13T21:35:28Z

Palika:

SingleEvent Scripts

2024-03-13T21:25:44Z

Palika: added crit HP status stuff

These events go into the <code>event_single.lua</code> file of your mod. As of version v0.7.25, you will need to copy this file from base PMDO into your mod first, then paste these scripts into it.

== Custom Boss Fight Win Conditions / End effects: ==
:'''Author:''' Palika

Want to have it so a boss fight has an alternative win condition than just "beat all enemies"? Want something special to happen when that win condition is met? If the answer is yes, you'll need to override the usual BeginBattleEvent and its corresponding CheckBossClearEvent and end_sequence responsible for these features with the Lua version.

=== Code ===
<pre>
---
-- Reimplementation of Audino's C# event for BeginBattleEvent.
-- This will allow us to inject custom function code before ending a battle
-- (such as clearing existing lava flows when a boss fight ends).
-- @tparam GameEventOwner owner
-- @tparam Character ownerChar
-- @tparam SingleCharContext context
-- @tparam table args Table of format {CustomClearEvent="NameOfFunctionThatRunsOnClear", [other arguments to said script]}
function SINGLE_CHAR_SCRIPT.LuaBeginBattleEvent(owner, ownerChar, context, args)
local MapCheckState = luanet.import_type('RogueEssence.Dungeon.MapCheckState')
local SingleCharScriptEvent = luanet.import_type('RogueEssence.Dungeon.SingleCharScriptEvent')

local map_clear_idx = 'map_clear_check'

if context.User ~= nil then return end
--if a custom clear event is not given, use the default one.
if args.CustomClearEvent == nil then args.CustomClearEvent = 'LuaCheckBossClearEvent' end

--Turn on Team Mode if allowed when the boss fight starts.
if _DUNGEON:CanUseTeamMode() then
_DUNGEON:SetTeamMode(true)
end

local clear_status = RogueEssence.Dungeon.MapStatus(map_clear_idx)
clear_status:LoadFromData()

local check = clear_status.StatusStates:GetWithDefault(luanet.ctype(MapCheckState))
--The 2nd argument in the function below needs a string that represents a lua table of the arguments to pass. Serpent.line will convert the lua table to a string representing it for us.
--We only NEED to pass args, as owner, ownerchar, and context are automatically passed in when the check event is called
check.CheckEvents:Add(SingleCharScriptEvent(args.CustomClearEvent, Serpent.line(args)))
--check.CheckEvents:Add(LuaCheckBossClearEvent(owner, ownerChar, context, args))

TASK:WaitTask(_DUNGEON:AddMapStatus(clear_status))
end

--Import Serpent library.
Serpent = require 'lib.serpent'

---
-- Reimplementation of the basic CheckBossClearEvent.
-- Call something different from LuaBeginBattleEvent or edit this accordingly if you
-- want a different wincon for your map or special effects/anims on win.
-- @tparam GameEventOwner owner
-- @tparam Character ownerChar Not used by this function.
-- @tparam SingleCharContext context Not used by this function.
-- @tparam table args Table of caller-defined arguments. Not used by this function.
function SINGLE_CHAR_SCRIPT.LuaCheckBossClearEvent(owner, ownerChar, context, args)
local MapCheckState = luanet.import_type('RogueEssence.Dungeon.MapCheckState')
local SingleCharScriptEvent = luanet.import_type('RogueEssence.Dungeon.SingleCharScriptEvent')

---
-- Sequence that runs when map is over. Fade out, cut the music, etc.
-- @usage Coroutine
function end_sequence()
_GAME:BGM("", true)

TASK:WaitTask(_GAME:FadeOut(false))

_DUNGEON:ResetTurns()

-- restore all and remove all map status
local statuses_to_remove = {}
for i = 0, _ZONE.CurrentMap.Status.Keys.Count - 1, 1 do
statuses_to_remove[i] = _ZONE.CurrentMap.Status.Keys[i]
end

for i = 0, #statuses_to_remove - 1, 1 do
TASK:WaitTask(_DUNGEON:RemoveMapStatus(statuses_to_remove[i], false))
end

-- heal everyone in the party
for i = 0, GAME:GetPlayerPartyCount() - 1, 1 do
_DATA.Save.ActiveTeam.Players[i]:FullRestore()
end

TASK:WaitTask(_GAME:EndSegment(RogueEssence.Data.GameProgress.ResultType.Cleared))

end

-- For each enemy team, check each chara in that team.
-- If any are still alive, then fail this check and return early.
for i = 0, _ZONE.CurrentMap.MapTeams.Count - 1, 1 do
local team = _ZONE.CurrentMap.MapTeams[i].Players
for j = 0, team.Count - 1, 1 do
-- Break and return early if even one enemy is not dead.
if not team[j].Dead then return end
end
end

-- Everyone's dead, clear the scene.
local checks = owner.StatusStates:GetWithDefault(luanet.ctype(MapCheckState))

-- The call originally for this was to remove(this), which isn't in lua.
-- So we need to find the LuaCheckBossClearEvent and remove that (remove ourself)
for i = 0, checks.CheckEvents.Count - 1, 1 do
if LUA_ENGINE:TypeOf(checks.CheckEvents[i]) == luanet.ctype(SingleCharScriptEvent) then
if checks.CheckEvents[i].Script == args.CustomClearEvent then
checks.CheckEvents:Remove(checks.CheckEvents[i])
end
end
end

if _DATA.CurrentReplay == nil then
TASK:WaitTask(end_sequence())
else
TASK:WaitTask(_GAME:EndSegment(RogueEssence.Data.GameProgress.ResultType.Cleared))
end

end
</pre>

=== Usage ===

The first function, <code>LuaBeginBattleEvent</code>, is responsible for letting PMDO know to look at <code>LuaCheckBossClearEvent</code> to determine when the map is won. Instead of the usual <code>BeginBattleEvent</code> in your boss fight's OnMapStart's Map Effects, you need to call a SingleCharScriptEvent for LuaBeginBattleEvent instead. It'll look like this:

[[File:LuaBeginBattleEvent.PNG]]

<code>LuaCheckBossClearEvent</code> is responsible for identifying when the map is won, and then the <code>end_sequence</code> function within it is responsible for fading stuff out and actually winning the map.

You won't need to modify the scripting for LuaBeginBattleEvent at all; it should remain as it is.

==== Tutorial: Alternate win condition ====
If you would like an alternate win condition or end sequence besides just fading out, then you will need to edit <code>LuaCheckBossClearEvent</code> and its <code>end_sequence</code> respectively.

# First, copy and rename your custom version of <code>LuaCheckBossClearEvent</code> to something more appropriately fitting.
#* Let's say we want a win condition where you only have to defeat the leader of a gang to win the boss fight. We'll call this function instead <code>CheckDefeatedGangLeader</code>. Copy the <code>LuaCheckBossClearEvent</code> function above and rename it to <code>CheckDefeatedGangLeader</code>.
# In <code>LuaBeginBattleEvent</code>, be sure to pass an argument of <code>CustomClearEvent = 'CheckDefeatedGangLeader'</code> when you define it in the MapEffects, so <code>LuaBeginBattleEvent</code> will knows to use your custom function instead of the default one given.
# Next, you need to modify how <code>CheckDefeatedGangLeader</code> identifies the win condition. If the win condition is failed, the function should return early. The default one does this by checking all enemy teams, and if any members on any team are not dead, then that means an enemy is still alive and the win condition has failed.
#* For our example, if our gang leader is a Scrafty, we should iterate through all enemy teams and see if we find a member that is both a Scrafty and alive. If so, then our win condition has failed and we should return early.
#* Alternatively, you can assign a LuaTable property to the Scrafty that marks it as, say, <code>.GangLeader = true</code>, and make sure that there are no NPCs with a LuaTable property of 'GangLeader' equal to true that are alive. Doing it like this would allow you to have as many GangLeaders as you may want that need to be defeated to meet the win condition.
# With all this done, when the Scrafty is defeated, the map should end and call <code>end_sequence()</code> as long as we aren't watching a replay. <code>end_sequence()</code> is responsible for fading the map and music out.
#* You can redefine it to anything you want if you want different things to happen when you actually win. For example, maybe you want your party members to face the camera and do a pose for a few seconds before the game fades out. You could accomplish this by writing code at the very top of end_sequence that makes all your party members do the face down and do the Pose animation!
#* You can do anything of course, but be careful not to remove things that may be important to handling the end of the dungeon adventure, such as the line of code responsible for ending the segment as Cleared.

== Causing a Wipe if allies faint: ==

Want to cause a party wipe in the event that a specific character faints? Perhaps the Hero/Partner characters? This is easily achievable again via pre-made Lua scripting to be placed within event_single.lua.

--Check to make sure nobody marked as "IsPartner" is dead. Check guests as well
--if one is dead, then cause an instant game over
--if someone died and they aren't "IsPartner", then send them home automatically.
function SINGLE_CHAR_SCRIPT.AllyDeathCheck(owner, ownerChar, context, args)
local player_count = GAME:GetPlayerPartyCount()
local guest_count = GAME:GetPlayerGuestCount()
if player_count < 1 then return end--If there's no party members then we dont need to do anything
for i = 0, player_count - 1, 1 do
local player = GAME:GetPlayerPartyMember(i)
if player.Dead and player.IsPartner then --someone died
for j = 0, player_count - 1, 1 do --beam everyone else out
player = GAME:GetPlayerPartyMember(j)
if not player.Dead then--dont beam out whoever died
--delay between beam outs
GAME:WaitFrames(60)
TASK:WaitTask(_DUNGEON:ProcessBattleFX(player, player, _DATA.SendHomeFX))
player.Dead = true
end
end
--beam out guests
for j = 0, guest_count - 1, 1 do --beam everyone else out
guest = GAME:GetPlayerGuestMember(j)
if not guest.Dead then--dont beam out whoever died
--delay between beam outs
GAME:WaitFrames(60)
TASK:WaitTask(_DUNGEON:ProcessBattleFX(guest, guest, _DATA.SendHomeFX))
guest.Dead = true
end
end
return--cut the script short here if someone died, no need to check guests
end
end

--check guests as well
if guest_count < 1 then return end--If there's no guest members then we dont need to do anything
for i = 0, guest_count - 1, 1 do
local guest = GAME:GetPlayerGuestMember(i)
if guest.Dead and guest.IsPartner then --someone died
--beam player's team out first
for j = 0, player_count - 1, 1 do --beam everyone else out
player = GAME:GetPlayerPartyMember(j)
if not player.Dead then--dont beam out whoever died
TASK:WaitTask(_DUNGEON:ProcessBattleFX(player, player, _DATA.SendHomeFX))
player.Dead = true
GAME:WaitFrames(60)
end
end
for j = 0, guest_count - 1, 1 do --beam everyone else out
guest = GAME:GetPlayerGuestMember(j)
if not guest.Dead then--dont beam out whoever died
TASK:WaitTask(_DUNGEON:ProcessBattleFX(guest, guest, _DATA.SendHomeFX))
guest.Dead = true
GAME:WaitFrames(60)
end
end
end
end

end

== Giving Exclamation points to low health allies ==

Want that cool little effect where characters low on HP have an exclamation point over their head? Using some pre-configured event_single Lua code and by configuring your own Critical Health status, you can achieve this cosmetic effect pretty easily.

First, let's configure the status effect that'll give the player the exclamation point over their head. Go to the Data tab on the Dev menu, then go to Statuses. Click the Add button on the menu that pops up, and it's here we'll configure our Critical Health status. Configure yours to match what you see in the image below. Anything you don't see in the window in this image can be left as the defaults.

[[File:CriticalHealthStatus.PNG]]

Next, insert this code into your event_single.lua file for your mod.

Code:
function SINGLE_CHAR_SCRIPT.SetCriticalHealthStatus(owner, ownerChar, context, args)
local player_count = GAME:GetPlayerPartyCount()
local critical = RogueEssence.Dungeon.StatusEffect("critical_health")
--initialize status data before adding it to anything
critical:LoadFromData()
for i = 0, player_count - 1, 1 do
local player = GAME:GetPlayerPartyMember(i)
if player.HP <= player.MaxHP / 4 and player:GetStatusEffect("critical_health") == nil then
TASK:WaitTask(player:AddStatusEffect(nil, critical, false))
elseif player.HP > player.MaxHP / 4 and player:GetStatusEffect("critical_health") ~= nil then
TASK:WaitTask(player:RemoveStatusEffect("critical_health"))
end
end
end

Once you've done that, we need to configure Universal to run this code at the end of turns. Click the Constants tab on the Dev menu, go to Universal, and scroll down until you find "On Turn Ends". Here, we'll add a SingleCharScriptEvent that calls SetCriticalHealthStatus on the end of turns, so the Critical Health status that displays the exclamation point is set or removed when someone's HP passes the 1/4 HP threshold. Your configuration should look like this in the end:

[[File:LowHealthExclamation.PNG]]

You should be all set! Your ally team members (not guests, you can expand this functionality yourself if you so wish to cover guests) will get an exclamation above their head and an informative status when they're low on HP.

[[File:LowHP.PNG]]

File:LowHP.PNG

2024-03-13T21:25:19Z

Palika:

File:LowHealthExclamation.PNG

2024-03-13T21:23:10Z

Palika:

File:CriticalHealthStatus.PNG

2024-03-13T21:19:50Z

Palika:

SingleEvent Scripts

2024-03-13T20:43:23Z

Palika: added serpent import

SingleEvent Scripts

2024-03-13T19:12:23Z

Palika:

Custom Boss Fight Win Conditions / End effects:

Want to have it so a boss fight has an alternative win condition than just "beat all enemies"? Want something special to happen when that win condition is met? If the answer is yes, you'll need to override the usual BeginBattleEvent and its corresponding CheckBossClearEvent and end_sequence responsible for these features with the lua version.

Luckily for you, the C# version of it has been reimplemented into Lua already for you. All you need to do is take the below code and copy and paste them into event_single.

--Reimplementing Audino's C# event for BeginBattleEvent.
--This will allow us to inject custom function code before ending a battle (such as clearing existing lava flows when a boss fight ends).
MapCheckState = luanet.import_type('RogueEssence.Dungeon.MapCheckState')
SingleCharScriptEvent = luanet.import_type('RogueEssence.Dungeon.SingleCharScriptEvent')

function SINGLE_CHAR_SCRIPT.LuaBeginBattleEvent(owner, ownerChar, context, args)

local map_clear_idx = 'map_clear_check'

if context.User ~= nil then return end
--if a custom clear event is not given, use the default one.
if args.CustomClearEvent == nil then args.CustomClearEvent = 'LuaCheckBossClearEvent' end

--Turn on Team Mode if allowed when the boss fight starts.
if _DUNGEON:CanUseTeamMode() then
_DUNGEON:SetTeamMode(true)
end

local clear_status = RogueEssence.Dungeon.MapStatus(map_clear_idx)
clear_status:LoadFromData()

local check = clear_status.StatusStates:GetWithDefault(luanet.ctype(MapCheckState))
--The 2nd argument in the function below needs a string that represents a lua table of the arguments to pass. Serpent.line will convert the lua table to a string representing it for us.
--We only NEED to pass args, as owner, ownerchar, and context are automatically passed in when the check event is called
check.CheckEvents:Add(SingleCharScriptEvent(args.CustomClearEvent, Serpent.line(args)))
--check.CheckEvents:Add(LuaCheckBossClearEvent(owner, ownerChar, context, args))

TASK:WaitTask(_DUNGEON:AddMapStatus(clear_status))
end

--Reimplementation of the basic CheckBossClearEvent.
--Call something different from LuaBeginBattleEvent or edit this accordingly if you want a different wincon for your map or special effects/anims on win.
function SINGLE_CHAR_SCRIPT.LuaCheckBossClearEvent(owner, ownerChar, context, args)

--Sequence that runs when map is over. Fade out, cut the music, etc.
function end_sequence()
_GAME:BGM("", true)

TASK:WaitTask(_GAME:FadeOut(false))

_DUNGEON:ResetTurns()

--restore all and remove all map status
local statuses_to_remove = {}
for i = 0, _ZONE.CurrentMap.Status.Keys.Count - 1, 1 do
statuses_to_remove[i] = _ZONE.CurrentMap.Status.Keys[i]
end

for i = 0, #statuses_to_remove - 1, 1 do
TASK:WaitTask(_DUNGEON:RemoveMapStatus(statuses_to_remove[i], false))
end

--heal everyone in the party
for i = 0, GAME:GetPlayerPartyCount() - 1, 1 do
_DATA.Save.ActiveTeam.Players[i]:FullRestore()
end

TASK:WaitTask(_GAME:EndSegment(RogueEssence.Data.GameProgress.ResultType.Cleared))

end

--For each enemy team, check each chara in that team. If any are still alive, then fail this check and return early.
for i = 0, _ZONE.CurrentMap.MapTeams.Count - 1, 1 do
local team = _ZONE.CurrentMap.MapTeams[i].Players
for j = 0, team.Count - 1, 1 do
--Break and return early if even one enemy is not dead.
if not team[j].Dead then return end
end
end

--Everyone's dead, clear the scene.
local checks = owner.StatusStates:GetWithDefault(luanet.ctype(MapCheckState))

--The call originally for this was to remove(this), which isn't in lua. So we need to find the LuaCheckBossClearEvent and remove that (remove ourself)
for i = 0, checks.CheckEvents.Count - 1, 1 do
if LUA_ENGINE:TypeOf(checks.CheckEvents[i]) == luanet.ctype(SingleCharScriptEvent) then
if checks.CheckEvents[i].Script == args.CustomClearEvent then
checks.CheckEvents:Remove(checks.CheckEvents[i])
end
end
end

if _DATA.CurrentReplay == nil then
TASK:WaitTask(end_sequence())
else
TASK:WaitTask(_GAME:EndSegment(RogueEssence.Data.GameProgress.ResultType.Cleared))
end

end

The first function, LuaBeginBattleEvent is responsible for letting PMDO know to look at LuaCheckBossClearEvent to determine when the map is won. Instead of the usual BeginBattleEvent in your boss fight's OnMapStart's Map Effects, you need to call a SingleCharScriptEvent for LuaBeginBattleEvent instead. It'll look like this:

[[File:LuaBeginBattleEvent.PNG]]

LuaCheckBossClearEvent is responsible for identifying when the map is won, and then the end_sequence function within it is responsible for fading stuff out and actually winning the map.

You won't need to modify the scripting for LuaBeginBattleEvent at all, it should remain as it is. If you need an alternate wincon/end sequence besides just fading out, then you need to edit LuaCheckBossClearEvent and its end_sequence respectively.

First thing's first, unless you want to be lazy, you should rename your custom version of LuaCheckBossClearEvent to something more appropriately fitting. Let's say we want a win con where you only have to defeat the leader of a gang to win the boss fight. We'll call this function instead CheckDefeatedGangLeader. Take the LuaCheckBossClearEvent and all its code, and just rename it to CheckDefeatedGangLeader.

Now, in LuaBeginBattleEvent, be sure to pass an argument of CustomClearEvent = 'CheckDefeatedGangLeader' when you define it in the MapEffects so the LuaBeginBattleEvent knows to use your custom function instead of the default one given.

Next, you need to modify how CheckDefeatedGangLeader identifies the wincon. You should write it in a way that has the function return early if the win condition is failed. The default one does this by checking all enemy teams, and if any members on any team is not dead, then that means an enemy is still alive and the win condition has failed.

For our example, if our gang leader is a Scrafty, we should iterate through all enemy teams and see if we find a member that is both a Scrafty and alive. If so, then our win condition has failed and we should end early. Alternatively, you can assign a LuaTable property to the Scrafty that marks it as, say, 'GangLeader' = true, and make sure that there are no NPCs with a LuaTable property of 'GangLeader' equal to true that are alive. Doing it like this would allow you to have as many GangLeaders as you may want that need to be defeated to meet the wincon.

Now, with all this out of the way, when the Scrafty is defeated, the map should end and call end_sequence() (as long as we aren't watching a replay). end_sequence() is responsible for fading the map and music out. You can redefine it to anything you want if you want different things to happen when you actually win. For example, maybe you want your party members to face the camera and do a pose for a few seconds before the game fades out. You could accomplish this by writing code at the very top of end_sequence that makes all your party members do the face down and do the Pose animation! You can do anything of course, but be careful not to remove things that are important unless you know what you're doing, such as the line of code responsible for ending the segment as Cleared.

SingleEvent Scripts

2024-03-13T19:11:53Z

Palika:

Custom Boss Fight Win Conditions / End effects:

Want to have it so a boss fight has an alternative win condition than just "beat all enemies"? Want something special to happen when that win condition is met? If the answer is yes, you'll need to override the usual BeginBattleEvent and its corresponding CheckBossClearEvent and end_sequence responsible for these features with the lua version.

Luckily for you, the C# version of it has been reimplemented into Lua already for you. All you need to do is take the below code and copy and paste them into event_single.

--Reimplementing Audino's C# event for BeginBattleEvent.
--This will allow us to inject custom function code before ending a battle (such as clearing existing lava flows when a boss fight ends).
MapCheckState = luanet.import_type('RogueEssence.Dungeon.MapCheckState')
SingleCharScriptEvent = luanet.import_type('RogueEssence.Dungeon.SingleCharScriptEvent')

function SINGLE_CHAR_SCRIPT.LuaBeginBattleEvent(owner, ownerChar, context, args)

local map_clear_idx = 'map_clear_check'

if context.User ~= nil then return end
--if a custom clear event is not given, use the default one.
if args.CustomClearEvent == nil then args.CustomClearEvent = 'LuaCheckBossClearEvent' end

--Turn on Team Mode if allowed when the boss fight starts.
if _DUNGEON:CanUseTeamMode() then
_DUNGEON:SetTeamMode(true)
end

local clear_status = RogueEssence.Dungeon.MapStatus(map_clear_idx)
clear_status:LoadFromData()

local check = clear_status.StatusStates:GetWithDefault(luanet.ctype(MapCheckState))
--The 2nd argument in the function below needs a string that represents a lua table of the arguments to pass. Serpent.line will convert the lua table to a string representing it for us.
--We only NEED to pass args, as owner, ownerchar, and context are automatically passed in when the check event is called
check.CheckEvents:Add(SingleCharScriptEvent(args.CustomClearEvent, Serpent.line(args)))
--check.CheckEvents:Add(LuaCheckBossClearEvent(owner, ownerChar, context, args))

TASK:WaitTask(_DUNGEON:AddMapStatus(clear_status))
end

--Reimplementation of the basic CheckBossClearEvent.
--Call something different from LuaBeginBattleEvent or edit this accordingly if you want a different wincon for your map or special effects/anims on win.
function SINGLE_CHAR_SCRIPT.LuaCheckBossClearEvent(owner, ownerChar, context, args)

--Sequence that runs when map is over. Fade out, cut the music, etc.
function end_sequence()
_GAME:BGM("", true)

TASK:WaitTask(_GAME:FadeOut(false))

_DUNGEON:ResetTurns()

--restore all and remove all map status
local statuses_to_remove = {}
for i = 0, _ZONE.CurrentMap.Status.Keys.Count - 1, 1 do
statuses_to_remove[i] = _ZONE.CurrentMap.Status.Keys[i]
end

for i = 0, #statuses_to_remove - 1, 1 do
TASK:WaitTask(_DUNGEON:RemoveMapStatus(statuses_to_remove[i], false))
end

--heal everyone in the party
for i = 0, GAME:GetPlayerPartyCount() - 1, 1 do
_DATA.Save.ActiveTeam.Players[i]:FullRestore()
end

TASK:WaitTask(_GAME:EndSegment(RogueEssence.Data.GameProgress.ResultType.Cleared))

end

--For each enemy team, check each chara in that team. If any are still alive, then fail this check and return early.
for i = 0, _ZONE.CurrentMap.MapTeams.Count - 1, 1 do
local team = _ZONE.CurrentMap.MapTeams[i].Players
for j = 0, team.Count - 1, 1 do
--Break and return early if even one enemy is not dead.
if not team[j].Dead then return end
end
end

--Everyone's dead, clear the scene.
local checks = owner.StatusStates:GetWithDefault(luanet.ctype(MapCheckState))

--The call originally for this was to remove(this), which isn't in lua. So we need to find the LuaCheckBossClearEvent and remove that (remove ourself)
for i = 0, checks.CheckEvents.Count - 1, 1 do
if LUA_ENGINE:TypeOf(checks.CheckEvents[i]) == luanet.ctype(SingleCharScriptEvent) then
if checks.CheckEvents[i].Script == args.CustomClearEvent then
checks.CheckEvents:Remove(checks.CheckEvents[i])
end
end
end

if _DATA.CurrentReplay == nil then
TASK:WaitTask(end_sequence())
else
TASK:WaitTask(_GAME:EndSegment(RogueEssence.Data.GameProgress.ResultType.Cleared))
end

end

The first function, LuaBeginBattleEvent is responsible for letting PMDO know to look at LuaCheckBossClearEvent to determine when the map is won. Instead of the usual BeginBattleEvent in your boss fight's OnMapStart's Map Effects, you need to call a SingleCharScriptEvent for LuaBeginBattleEvent instead. It'll look like this:

[[File:LuaBeginBattleEvent.png]]

LuaCheckBossClearEvent is responsible for identifying when the map is won, and then the end_sequence function within it is responsible for fading stuff out and actually winning the map.

You won't need to modify the scripting for LuaBeginBattleEvent at all, it should remain as it is. If you need an alternate wincon/end sequence besides just fading out, then you need to edit LuaCheckBossClearEvent and its end_sequence respectively.

First thing's first, unless you want to be lazy, you should rename your custom version of LuaCheckBossClearEvent to something more appropriately fitting. Let's say we want a win con where you only have to defeat the leader of a gang to win the boss fight. We'll call this function instead CheckDefeatedGangLeader. Take the LuaCheckBossClearEvent and all its code, and just rename it to CheckDefeatedGangLeader.

Now, in LuaBeginBattleEvent, be sure to pass an argument of CustomClearEvent = 'CheckDefeatedGangLeader' when you define it in the MapEffects so the LuaBeginBattleEvent knows to use your custom function instead of the default one given.

Next, you need to modify how CheckDefeatedGangLeader identifies the wincon. You should write it in a way that has the function return early if the win condition is failed. The default one does this by checking all enemy teams, and if any members on any team is not dead, then that means an enemy is still alive and the win condition has failed.

For our example, if our gang leader is a Scrafty, we should iterate through all enemy teams and see if we find a member that is both a Scrafty and alive. If so, then our win condition has failed and we should end early. Alternatively, you can assign a LuaTable property to the Scrafty that marks it as, say, 'GangLeader' = true, and make sure that there are no NPCs with a LuaTable property of 'GangLeader' equal to true that are alive. Doing it like this would allow you to have as many GangLeaders as you may want that need to be defeated to meet the wincon.

Now, with all this out of the way, when the Scrafty is defeated, the map should end and call end_sequence() (as long as we aren't watching a replay). end_sequence() is responsible for fading the map and music out. You can redefine it to anything you want if you want different things to happen when you actually win. For example, maybe you want your party members to face the camera and do a pose for a few seconds before the game fades out. You could accomplish this by writing code at the very top of end_sequence that makes all your party members do the face down and do the Pose animation! You can do anything of course, but be careful not to remove things that are important unless you know what you're doing, such as the line of code responsible for ending the segment as Cleared.

SingleEvent Scripts

2024-03-13T19:11:19Z

Palika: Created page with " Custom Boss Fight Win Conditions / End effects: Want to have it so a boss fight has an alternative win condition than just "beat all enemies"? Want something special to happen when that win condition is met? If the answer is yes, you'll need to override the usual BeginBattleEvent and its corresponding CheckBossClearEvent and end_sequence responsible for these features with the lua version. Luckily for you, the C# version of it has been reimplemented into Lua already f..."

Custom Boss Fight Win Conditions / End effects:

Want to have it so a boss fight has an alternative win condition than just "beat all enemies"? Want something special to happen when that win condition is met? If the answer is yes, you'll need to override the usual BeginBattleEvent and its corresponding CheckBossClearEvent and end_sequence responsible for these features with the lua version.

Luckily for you, the C# version of it has been reimplemented into Lua already for you. All you need to do is take the below code and copy and paste them into event_single.

--Reimplementing Audino's C# event for BeginBattleEvent.
--This will allow us to inject custom function code before ending a battle (such as clearing existing lava flows when a boss fight ends).
MapCheckState = luanet.import_type('RogueEssence.Dungeon.MapCheckState')
SingleCharScriptEvent = luanet.import_type('RogueEssence.Dungeon.SingleCharScriptEvent')

function SINGLE_CHAR_SCRIPT.LuaBeginBattleEvent(owner, ownerChar, context, args)

local map_clear_idx = 'map_clear_check'

if context.User ~= nil then return end
--if a custom clear event is not given, use the default one.
if args.CustomClearEvent == nil then args.CustomClearEvent = 'LuaCheckBossClearEvent' end

--Turn on Team Mode if allowed when the boss fight starts.
if _DUNGEON:CanUseTeamMode() then
_DUNGEON:SetTeamMode(true)
end

local clear_status = RogueEssence.Dungeon.MapStatus(map_clear_idx)
clear_status:LoadFromData()

local check = clear_status.StatusStates:GetWithDefault(luanet.ctype(MapCheckState))
--The 2nd argument in the function below needs a string that represents a lua table of the arguments to pass. Serpent.line will convert the lua table to a string representing it for us.
--We only NEED to pass args, as owner, ownerchar, and context are automatically passed in when the check event is called
check.CheckEvents:Add(SingleCharScriptEvent(args.CustomClearEvent, Serpent.line(args)))
--check.CheckEvents:Add(LuaCheckBossClearEvent(owner, ownerChar, context, args))

TASK:WaitTask(_DUNGEON:AddMapStatus(clear_status))
end

--Reimplementation of the basic CheckBossClearEvent.
--Call something different from LuaBeginBattleEvent or edit this accordingly if you want a different wincon for your map or special effects/anims on win.
function SINGLE_CHAR_SCRIPT.LuaCheckBossClearEvent(owner, ownerChar, context, args)

--Sequence that runs when map is over. Fade out, cut the music, etc.
function end_sequence()
_GAME:BGM("", true)

TASK:WaitTask(_GAME:FadeOut(false))

_DUNGEON:ResetTurns()

--restore all and remove all map status
local statuses_to_remove = {}
for i = 0, _ZONE.CurrentMap.Status.Keys.Count - 1, 1 do
statuses_to_remove[i] = _ZONE.CurrentMap.Status.Keys[i]
end

for i = 0, #statuses_to_remove - 1, 1 do
TASK:WaitTask(_DUNGEON:RemoveMapStatus(statuses_to_remove[i], false))
end

--heal everyone in the party
for i = 0, GAME:GetPlayerPartyCount() - 1, 1 do
_DATA.Save.ActiveTeam.Players[i]:FullRestore()
end

TASK:WaitTask(_GAME:EndSegment(RogueEssence.Data.GameProgress.ResultType.Cleared))

end

--For each enemy team, check each chara in that team. If any are still alive, then fail this check and return early.
for i = 0, _ZONE.CurrentMap.MapTeams.Count - 1, 1 do
local team = _ZONE.CurrentMap.MapTeams[i].Players
for j = 0, team.Count - 1, 1 do
--Break and return early if even one enemy is not dead.
if not team[j].Dead then return end
end
end

--Everyone's dead, clear the scene.
local checks = owner.StatusStates:GetWithDefault(luanet.ctype(MapCheckState))

--The call originally for this was to remove(this), which isn't in lua. So we need to find the LuaCheckBossClearEvent and remove that (remove ourself)
for i = 0, checks.CheckEvents.Count - 1, 1 do
if LUA_ENGINE:TypeOf(checks.CheckEvents[i]) == luanet.ctype(SingleCharScriptEvent) then
if checks.CheckEvents[i].Script == args.CustomClearEvent then
checks.CheckEvents:Remove(checks.CheckEvents[i])
end
end
end

if _DATA.CurrentReplay == nil then
TASK:WaitTask(end_sequence())
else
TASK:WaitTask(_GAME:EndSegment(RogueEssence.Data.GameProgress.ResultType.Cleared))
end

end

The first function, LuaBeginBattleEvent is responsible for letting PMDO know to look at LuaCheckBossClearEvent to determine when the map is won. Instead of the usual BeginBattleEvent in your boss fight's OnMapStart's Map Effects, you need to call a SingleCharScriptEvent for LuaBeginBattleEvent instead. It'll look like this:

[[File:<LuaBeginBattleEvent>.png]]

LuaCheckBossClearEvent is responsible for identifying when the map is won, and then the end_sequence function within it is responsible for fading stuff out and actually winning the map.

You won't need to modify the scripting for LuaBeginBattleEvent at all, it should remain as it is. If you need an alternate wincon/end sequence besides just fading out, then you need to edit LuaCheckBossClearEvent and its end_sequence respectively.

First thing's first, unless you want to be lazy, you should rename your custom version of LuaCheckBossClearEvent to something more appropriately fitting. Let's say we want a win con where you only have to defeat the leader of a gang to win the boss fight. We'll call this function instead CheckDefeatedGangLeader. Take the LuaCheckBossClearEvent and all its code, and just rename it to CheckDefeatedGangLeader.

Now, in LuaBeginBattleEvent, be sure to pass an argument of CustomClearEvent = 'CheckDefeatedGangLeader' when you define it in the MapEffects so the LuaBeginBattleEvent knows to use your custom function instead of the default one given.

Next, you need to modify how CheckDefeatedGangLeader identifies the wincon. You should write it in a way that has the function return early if the win condition is failed. The default one does this by checking all enemy teams, and if any members on any team is not dead, then that means an enemy is still alive and the win condition has failed.

For our example, if our gang leader is a Scrafty, we should iterate through all enemy teams and see if we find a member that is both a Scrafty and alive. If so, then our win condition has failed and we should end early. Alternatively, you can assign a LuaTable property to the Scrafty that marks it as, say, 'GangLeader' = true, and make sure that there are no NPCs with a LuaTable property of 'GangLeader' equal to true that are alive. Doing it like this would allow you to have as many GangLeaders as you may want that need to be defeated to meet the wincon.

Now, with all this out of the way, when the Scrafty is defeated, the map should end and call end_sequence() (as long as we aren't watching a replay). end_sequence() is responsible for fading the map and music out. You can redefine it to anything you want if you want different things to happen when you actually win. For example, maybe you want your party members to face the camera and do a pose for a few seconds before the game fades out. You could accomplish this by writing code at the very top of end_sequence that makes all your party members do the face down and do the Pose animation! You can do anything of course, but be careful not to remove things that are important unless you know what you're doing, such as the line of code responsible for ending the segment as Cleared.

File:LuaBeginBattleEvent.PNG

2024-03-13T18:55:18Z

Palika:

Tutorial:Partner Following

2023-12-23T21:12:24Z

Palika:

Want your partner to follow you around in the overworld? It'll take some scripting work as well as map editor work to achieve this. Let's start with the map editor.

You'll need to place down a spawner that the script will use to spawn in your partner. You can do this in the Entities tab, and choosing an object type of spawner. Let's work with the assumption that your partner will be whoever is in slot 2 of your party. In such a case, we'll call the spawner TEAMMATE_1 and the entity it spawns Teammate1, as seen below.

[[File:Partner_Spawner.PNG|frameless]]

Place the spawner wherever in the map you want the partner to spawn in. You can also set the default direction they spawn in as by changing the direction of the spawner. Once this is done, save your map changes. It's now time to make changes to the init script for the ground so the game knows what to do with that spawner.

Open up your init script and look at the Init callback function. Here, you'll need to add several functions related to spawning in and setting up your partner.

You'll need to start with calling COMMON.RespawnAllies(). This will call the spawner you made earlier. From here, you'll need to set up your partner's data and AI. You can do this with the following commands:

<pre>
local partner = CH('Teammate1')
AI:SetcharacterAI(partner, 'ai.ground_partner', CH('PLAYER'), partner.Position)
partner.CollisionDisabled = true
</pre>

This will initialize the ground character you spawned in (known internally as 'Teammate1') with the partner following AI, targeted at following the player character. Then, it'll disable their collision, as otherwise you'll get stuck on them constantly.

Assuming your init script was fresh before starting, it'll look something like this afterwards:
<pre>
function YourGroundName.Init(map)
MapStrings = COMMON.AutoLoadLocalizedStrings()
COMMON.RespawnAllies()
local partner = CH('Teammate1')
AI:SetcharacterAI(partner, 'ai.ground_partner', CH('PLAYER'), partner.Position)
partner.CollisionDisabled = true
end
</pre>

Now, whenever the map loads, the character in slot 2 of the party will follow you around that map! You'll need to set this up for every map you want the partner to follow you around in.

[[File:Partner_Following.PNG|frameless]]

=== What if the player/partner isn't in the party, but I want them to be the overworld Pokemon? ===
To do this, you'll have to set things up a bit differently. You'll want to call your spawner PARTNER_SPAWN and have the spawned entity called "Partner", as seen below.

[[File:Partner_Spawner_Method_2.PNG|frameless]]

Next, you'll need to adjust the values in Scriptvars's test_grounds data to be the player/partner you want. You'll see in the screenshot below variables that correspond to the player/partner's appearance.

[[File:Partner_Scriptvars.PNG|frameless]]

-Species = lower case string of the species of Pokemon.
-Form = The number for the form of the mon. This should be 0, unless you want to use a non default form of a pokemon (for example, Hisuian Zorua). Then, you need to change that to the number that corresponds to that form, which you can figure out with the dropdown in dev menu's Player tab. Just make sure you have the correct species selected first.
-skin = should be "normal" or "shiny", but can be other things if your mod includes additional skin types
-Gender = Set to 0 for Genderless, 1 for male, and 2 for female.

You'll do the rest of this the same as before, but you'll replace the COMMON.RespawnAllies call with COMMON.RespawnStarterPartner(). Additionally, you'll need to refer to the partner as "Partner" rather than "Teammate1". So you'll end up with:

<pre>
function YourGroundName.Init(map)
MapStrings = COMMON.AutoLoadLocalizedStrings()
COMMON.RespawnStarterPartner()
local partner = CH('Partner')
AI:SetcharacterAI(partner, 'ai.ground_partner', CH('PLAYER'), partner.Position)
partner.CollisionDisabled = true
end
</pre>

And presto, even though my party consists of the Kanto starters, in the overworld I am a Pikachu and an Eevee.

[[File:Partner_Party_Mismatch.PNG|frameless]]

Of course, you're free to reimplement these functions to better suit your needs (or to have variables with better names), but the quick and dirty way is to reuse the functions provided by base PMDO's COMMON functionality as described above. Just be sure to read the code for the functions you're using above to get a grasp of how they work first.

=== What if my map has multiple entrances? ===
The partner can only spawn in one place, and that's where the spawner is placed on the map. If you want them to appear next to you when you enter a hub world map from one of its many entrances, you'll need to add logic that gets triggered in the Enter callback for that map that teleports them to the player's side while the game is still faded out. You can do this in a number of ways, but one such way would be to have a variable get updated when leaving one map and going to the map with multiple entrances that lets the multiple entrance map's script know where to teleport the partner to.

For example, Halcyon has a system for this where a variable keeps track of the marker to teleport the partner to on the next map when a different map is exited. The partner gets teleported to this marker when the new map loads but before it fades in. The object responsible for map transitions on the different maps is what needs to update this variable, mind you, so if you want to see an example of this, be sure to check those map transition objects.

=== My partner doesn't spawn behind me when I save and reload! Why? ===
The ground map by default doesn't discriminate between loading in via a map transition or loading in via loading a saved game. You'll need to introduce your own logic to handle this. One such way is adding a function to the GameSave callback that saves to Scriptvars the position and direction of the partner. Then, add another function to the GameLoad callback that teleports the partner to the position and direction that was saved earlier. Halcyon has an example of this you can look at or reuse if you'd like.

Tutorial:Partner Following

2023-12-23T21:11:22Z

Palika:

Want your partner to follow you around in the overworld? It'll take some scripting work as well as map editor work to achieve this. Let's start with the map editor.

You'll need to place down a spawner that the script will use to spawn in your partner. You can do this in the Entities tab, and choosing an object type of spawner. Let's work with the assumption that your partner will be whoever is in slot 2 of your party. In such a case, we'll call the spawner TEAMMATE_1 and the entity it spawns Teammate1, as seen below.

[[File:Partner_Spawner.PNG|frameless]]

Place the spawner wherever in the map you want the partner to spawn in. You can also set the default direction they spawn in as by changing the direction of the spawner. Once this is done, save your map changes. It's now time to make changes to the init script for the ground so the game knows what to do with that spawner.

Open up your init script and look at the Init callback function. Here, you'll need to add several functions related to spawning in and setting up your partner.

You'll need to start with calling COMMON.RespawnAllies(). This will call the spawner you made earlier. From here, you'll need to set up your partner's data and AI. You can do this with the following commands:

<pre>
local partner = CH('Teammate1')
AI:SetcharacterAI(partner, 'ai.ground_partner', CH('PLAYER'), partner.Position)
partner.CollisionDisabled = true
</pre>

This will initialize the ground character you spawned in (known internally as 'Teammate1') with the partner following AI, targeted at following the player character. Then, it'll disable their collision, as otherwise you'll get stuck on them constantly.

Assuming your init script was fresh before starting, it'll look something like this afterwards:
<pre>
function YourGroundName.Init(map)
MapStrings = COMMON.AutoLoadLocalizedStrings()
COMMON.RespawnAllies()
local partner = CH('Teammate1')
AI:SetcharacterAI(partner, 'ai.ground_partner', CH('PLAYER'), partner.Position)
partner.CollisionDisabled = true
end
</pre>

Now, whenever the map loads, the character in slot 2 of the party will follow you around that map! You'll need to set this up for every map you want the partner to follow you around in.

[[File:Partner_Following.PNG|frameless]]

=== What if the player/partner isn't in the party, but I want them to be the overworld Pokemon? ===
To do this, you'll have to set things up a bit differently. You'll want to call your spawner PARTNER_SPAWN and have the spawned entity called "Partner", as seen below.

[[File:Partner_Spawner_Method_2.PNG|frameless]]

Next, you'll need to adjust the values in Scriptvars's test_grounds data to be the player/partner you want. You'll see in the screenshot below variables that correspond to the player/partner's appearance.

[[File:Partner_Scriptvars.PNG|frameless]]

-Species = lower case string of the species of Pokemon.
-Form = The number for the form of the mon. This should be 0, unless you want to use a non default form of a pokemon (for example, Hisuian Zorua). Then, you need to change that to the number that corresponds to that form, which you can figure out with the dropdown in dev menu's Player tab. Just make sure you have the correct species selected first.
-skin = should be "normal" or "shiny", but can be other things if your mod includes additional skin types
-Gender = Set to 0 for Genderless, 1 for male, and 2 for female.

You'll do the rest of this the same as before, but you'll replace the COMMON.RespawnAllies call with COMMON.RespawnStarterPartner(). Additionally, you'll need to refer to the partner as "Partner" rather than "Teammate1". So you'll end up with:

<pre>
function YourGroundName.Init(map)
MapStrings = COMMON.AutoLoadLocalizedStrings()
COMMON.RespawnStarterPartner()
local partner = CH('Partner')
AI:SetcharacterAI(partner, 'ai.ground_partner', CH('PLAYER'), partner.Position)
partner.CollisionDisabled = true
end
</pre>

And presto, even though my party consists of the Kanto starters, in the overworld I am a Pikachu and an Eevee.

[[File:Partner_Mismatch.PNG|frameless]]

Of course, you're free to reimplement these functions to better suit your needs (or to have variables with better names), but the quick and dirty way is to reuse the functions provided by base PMDO's COMMON functionality as described above. Just be sure to read the code for the functions you're using above to get a grasp of how they work first.

=== What if my map has multiple entrances? ===
The partner can only spawn in one place, and that's where the spawner is placed on the map. If you want them to appear next to you when you enter a hub world map from one of its many entrances, you'll need to add logic that gets triggered in the Enter callback for that map that teleports them to the player's side while the game is still faded out. You can do this in a number of ways, but one such way would be to have a variable get updated when leaving one map and going to the map with multiple entrances that lets the multiple entrance map's script know where to teleport the partner to.

For example, Halcyon has a system for this where a variable keeps track of the marker to teleport the partner to on the next map when a different map is exited. The partner gets teleported to this marker when the new map loads but before it fades in. The object responsible for map transitions on the different maps is what needs to update this variable, mind you, so if you want to see an example of this, be sure to check those map transition objects.

=== My partner doesn't spawn behind me when I save and reload! Why? ===
The ground map by default doesn't discriminate between loading in via a map transition or loading in via loading a saved game. You'll need to introduce your own logic to handle this. One such way is adding a function to the GameSave callback that saves to Scriptvars the position and direction of the partner. Then, add another function to the GameLoad callback that teleports the partner to the position and direction that was saved earlier. Halcyon has an example of this you can look at or reuse if you'd like.

Tutorial:Partner Following

2023-12-23T21:11:03Z

Palika:

Want your partner to follow you around in the overworld? It'll take some scripting work as well as map editor work to achieve this. Let's start with the map editor.

You'll need to place down a spawner that the script will use to spawn in your partner. You can do this in the Entities tab, and choosing an object type of spawner. Let's work with the assumption that your partner will be whoever is in slot 2 of your party. In such a case, we'll call the spawner TEAMMATE_1 and the entity it spawns Teammate1, as seen below.

[[File:Partner_Spawner.PNG|frameless]]

Place the spawner wherever in the map you want the partner to spawn in. You can also set the default direction they spawn in as by changing the direction of the spawner. Once this is done, save your map changes. It's now time to make changes to the init script for the ground so the game knows what to do with that spawner.

Open up your init script and look at the Init callback function. Here, you'll need to add several functions related to spawning in and setting up your partner.

You'll need to start with calling COMMON.RespawnAllies(). This will call the spawner you made earlier. From here, you'll need to set up your partner's data and AI. You can do this with the following commands:

<pre>
local partner = CH('Teammate1')
AI:SetcharacterAI(partner, 'ai.ground_partner', CH('PLAYER'), partner.Position)
partner.CollisionDisabled = true
</pre>

This will initialize the ground character you spawned in (known internally as 'Teammate1') with the partner following AI, targeted at following the player character. Then, it'll disable their collision, as otherwise you'll get stuck on them constantly.

Assuming your init script was fresh before starting, it'll look something like this afterwards:
<pre>
function YourGroundName.Init(map)
MapStrings = COMMON.AutoLoadLocalizedStrings()
COMMON.RespawnAllies()
local partner = CH('Teammate1')
AI:SetcharacterAI(partner, 'ai.ground_partner', CH('PLAYER'), partner.Position)
partner.CollisionDisabled = true
end
</pre>

Now, whenever the map loads, the character in slot 2 of the party will follow you around that map! You'll need to set this up for every map you want the partner to follow you around in.

[[File:Partner_Following.png|frameless]]

=== What if the player/partner isn't in the party, but I want them to be the overworld Pokemon? ===
To do this, you'll have to set things up a bit differently. You'll want to call your spawner PARTNER_SPAWN and have the spawned entity called "Partner", as seen below.

[[File:Partner_Spawner_Method_2.png|frameless]]

Next, you'll need to adjust the values in Scriptvars's test_grounds data to be the player/partner you want. You'll see in the screenshot below variables that correspond to the player/partner's appearance.

[[File:Partner_Scriptvars.png|frameless]]

-Species = lower case string of the species of Pokemon.
-Form = The number for the form of the mon. This should be 0, unless you want to use a non default form of a pokemon (for example, Hisuian Zorua). Then, you need to change that to the number that corresponds to that form, which you can figure out with the dropdown in dev menu's Player tab. Just make sure you have the correct species selected first.
-skin = should be "normal" or "shiny", but can be other things if your mod includes additional skin types
-Gender = Set to 0 for Genderless, 1 for male, and 2 for female.

You'll do the rest of this the same as before, but you'll replace the COMMON.RespawnAllies call with COMMON.RespawnStarterPartner(). Additionally, you'll need to refer to the partner as "Partner" rather than "Teammate1". So you'll end up with:

<pre>
function YourGroundName.Init(map)
MapStrings = COMMON.AutoLoadLocalizedStrings()
COMMON.RespawnStarterPartner()
local partner = CH('Partner')
AI:SetcharacterAI(partner, 'ai.ground_partner', CH('PLAYER'), partner.Position)
partner.CollisionDisabled = true
end
</pre>

And presto, even though my party consists of the Kanto starters, in the overworld I am a Pikachu and an Eevee.

[[File:Partner_Mismatch.png|frameless]]

Of course, you're free to reimplement these functions to better suit your needs (or to have variables with better names), but the quick and dirty way is to reuse the functions provided by base PMDO's COMMON functionality as described above. Just be sure to read the code for the functions you're using above to get a grasp of how they work first.

=== What if my map has multiple entrances? ===
The partner can only spawn in one place, and that's where the spawner is placed on the map. If you want them to appear next to you when you enter a hub world map from one of its many entrances, you'll need to add logic that gets triggered in the Enter callback for that map that teleports them to the player's side while the game is still faded out. You can do this in a number of ways, but one such way would be to have a variable get updated when leaving one map and going to the map with multiple entrances that lets the multiple entrance map's script know where to teleport the partner to.

For example, Halcyon has a system for this where a variable keeps track of the marker to teleport the partner to on the next map when a different map is exited. The partner gets teleported to this marker when the new map loads but before it fades in. The object responsible for map transitions on the different maps is what needs to update this variable, mind you, so if you want to see an example of this, be sure to check those map transition objects.

=== My partner doesn't spawn behind me when I save and reload! Why? ===
The ground map by default doesn't discriminate between loading in via a map transition or loading in via loading a saved game. You'll need to introduce your own logic to handle this. One such way is adding a function to the GameSave callback that saves to Scriptvars the position and direction of the partner. Then, add another function to the GameLoad callback that teleports the partner to the position and direction that was saved earlier. Halcyon has an example of this you can look at or reuse if you'd like.

File:Partner Spawner Method 2.PNG

2023-12-23T21:06:31Z

Palika: Uploaded with SimpleBatchUpload

[[Category: Tutorial Images]]

File:Partner Party Mismatch.PNG

2023-12-23T21:06:30Z

Palika: Uploaded with SimpleBatchUpload

[[Category: Tutorial Images]]

File:Partner Scriptvars.PNG

2023-12-23T21:06:30Z

Palika: Uploaded with SimpleBatchUpload

[[Category: Tutorial Images]]

File:Partner Following.PNG

2023-12-23T21:06:30Z

Palika: Uploaded with SimpleBatchUpload

[[Category: Tutorial Images]]

Tutorial:Partner Following

2023-12-23T21:04:24Z

Palika:

Want your partner to follow you around in the overworld? It'll take some scripting work as well as map editor work to achieve this. Let's start with the map editor.

You'll need to place down a spawner that the script will use to spawn in your partner. You can do this in the Entities tab, and choosing an object type of spawner. Let's work with the assumption that your partner will be whoever is in slot 2 of your party. In such a case, we'll call the spawner TEAMMATE_1 and the entity it spawns Teammate1, as seen below.

[[File:Partner_Spawner.png|frameless]]

Place the spawner wherever in the map you want the partner to spawn in. You can also set the default direction they spawn in as by changing the direction of the spawner. Once this is done, save your map changes. It's now time to make changes to the init script for the ground so the game knows what to do with that spawner.

Open up your init script and look at the Init callback function. Here, you'll need to add several functions related to spawning in and setting up your partner.

You'll need to start with calling COMMON.RespawnAllies(). This will call the spawner you made earlier. From here, you'll need to set up your partner's data and AI. You can do this with the following commands:

<pre>
local partner = CH('Teammate1')
AI:SetcharacterAI(partner, 'ai.ground_partner', CH('PLAYER'), partner.Position)
partner.CollisionDisabled = true
</pre>

This will initialize the ground character you spawned in (known internally as 'Teammate1') with the partner following AI, targeted at following the player character. Then, it'll disable their collision, as otherwise you'll get stuck on them constantly.

Assuming your init script was fresh before starting, it'll look something like this afterwards:
<pre>
function YourGroundName.Init(map)
MapStrings = COMMON.AutoLoadLocalizedStrings()
COMMON.RespawnAllies()
local partner = CH('Teammate1')
AI:SetcharacterAI(partner, 'ai.ground_partner', CH('PLAYER'), partner.Position)
partner.CollisionDisabled = true
end
</pre>

Now, whenever the map loads, the character in slot 2 of the party will follow you around that map! You'll need to set this up for every map you want the partner to follow you around in.

[[File:Partner_Following.png|frameless]]

=== What if the player/partner isn't in the party, but I want them to be the overworld Pokemon? ===
To do this, you'll have to set things up a bit differently. You'll want to call your spawner PARTNER_SPAWN and have the spawned entity called "Partner", as seen below.

[[File:Partner_Spawner_Method_2.png|frameless]]

Next, you'll need to adjust the values in Scriptvars's test_grounds data to be the player/partner you want. You'll see in the screenshot below variables that correspond to the player/partner's appearance.

[[File:Partner_Scriptvars.png|frameless]]

-Species = lower case string of the species of Pokemon.
-Form = The number for the form of the mon. This should be 0, unless you want to use a non default form of a pokemon (for example, Hisuian Zorua). Then, you need to change that to the number that corresponds to that form, which you can figure out with the dropdown in dev menu's Player tab. Just make sure you have the correct species selected first.
-skin = should be "normal" or "shiny", but can be other things if your mod includes additional skin types
-Gender = Set to 0 for Genderless, 1 for male, and 2 for female.

You'll do the rest of this the same as before, but you'll replace the COMMON.RespawnAllies call with COMMON.RespawnStarterPartner(). Additionally, you'll need to refer to the partner as "Partner" rather than "Teammate1". So you'll end up with:

<pre>
function YourGroundName.Init(map)
MapStrings = COMMON.AutoLoadLocalizedStrings()
COMMON.RespawnStarterPartner()
local partner = CH('Partner')
AI:SetcharacterAI(partner, 'ai.ground_partner', CH('PLAYER'), partner.Position)
partner.CollisionDisabled = true
end
</pre>

And presto, even though my party consists of the Kanto starters, in the overworld I am a Pikachu and an Eevee.

[[File:Partner_Mismatch.png|frameless]]

Of course, you're free to reimplement these functions to better suit your needs (or to have variables with better names), but the quick and dirty way is to reuse the functions provided by base PMDO's COMMON functionality as described above. Just be sure to read the code for the functions you're using above to get a grasp of how they work first.

=== What if my map has multiple entrances? ===
The partner can only spawn in one place, and that's where the spawner is placed on the map. If you want them to appear next to you when you enter a hub world map from one of its many entrances, you'll need to add logic that gets triggered in the Enter callback for that map that teleports them to the player's side while the game is still faded out. You can do this in a number of ways, but one such way would be to have a variable get updated when leaving one map and going to the map with multiple entrances that lets the multiple entrance map's script know where to teleport the partner to.

For example, Halcyon has a system for this where a variable keeps track of the marker to teleport the partner to on the next map when a different map is exited. The partner gets teleported to this marker when the new map loads but before it fades in. The object responsible for map transitions on the different maps is what needs to update this variable, mind you, so if you want to see an example of this, be sure to check those map transition objects.

=== My partner doesn't spawn behind me when I save and reload! Why? ===
The ground map by default doesn't discriminate between loading in via a map transition or loading in via loading a saved game. You'll need to introduce your own logic to handle this. One such way is adding a function to the GameSave callback that saves to Scriptvars the position and direction of the partner. Then, add another function to the GameLoad callback that teleports the partner to the position and direction that was saved earlier. Halcyon has an example of this you can look at or reuse if you'd like.

Tutorial:Partner Following

2023-12-23T20:50:46Z

Palika:

Tutorial:Partner Following

2023-12-23T20:41:05Z

Palika:

Tutorial:Partner Following

2023-12-23T20:34:29Z

Palika:

Tutorial:Partner Following

2023-12-23T20:33:48Z

Palika:

Tutorial:Partner Following

2023-12-23T20:12:56Z

Palika: Created page with "Want your partner to follow you around in the overworld? It'll take some scripting work as well as map editor work to achieve this. Let's start with the map editor. You'll need to place down a spawner that the script will use to spawn in your partner. You can do this in the Entities tab, and choosing an object type of spawner. Let's work with the assumption that your partner will be whoever is in slot 2 of your party. In such a case, we'll call the spawner TEAMMATE_1 an..."

File:Partner Spawner.PNG

2023-12-23T20:10:17Z

Palika: Uploaded with SimpleBatchUpload

Tutorial:Custom Floor Generation Steps

2023-07-07T00:11:29Z

Palika:

Sometimes, you may find that you want to add a feature to dungeon generation that just isn't possible with built in gen steps and tools. When this happens, you can script the generation step or feature in yourself by scripting via Lua by creating a FLOOR_GEN_SCRIPT in event_mapgen.lua. We'll walk through an example on how this was done for Halcyon's Illuminant Riverbed to show an example of how you can do this and some of the useful Lua functions you might need to do this.

Depending on what exactly you're trying to achieve with your custom gen step, you may want to start with the vanilla gen steps to get a base to work off of, or you may want to start with the Lua customization first. Either way, once you're ready to sit down and work with the Lua scripting, there's some basic functions/knowledge you'll need to know. There are more functions beyond these, but these are all we need for creating a river. You may find additional functions and tools to do things such as creating traps, items, or NPCs in the FLOOR_GEN_SCRIPT.Test function in event_mapgen.lua.

The function that defines your custom gen function should be given two parameters: map and args.
*Map is the floor you're on that you're generating. It includes a number of useful functions and variables such as:
**map.Width: Width of the map
**map.Height: Height of the map
**map.Rand:Next(x, y) - returns a random number, inclusive on lower and exclusive on upper, between x and y. This is important to use instead of math.random so that the dungeon's random seeding is used to generate the random number so replays and such are consistent.
**map:GetTile(loc) - gets the tile at the specified RogueElements.Loc(x,y).
**map:TrySetTile(loc, terrain) - attempts to set the tile at the specified location to the specified terrain type. May fail if the tile should not be changed for some reason (for example, it is the loc of the stairs, or is out of bounds)

*Args is a list of arguments given in the Arg table in the ScriptGenStep. Using these, you can write somewhat generic generation algorithms that can be tweaked on a per floor basis by giving different arguments to the function via the genstep's arg table depending on what floor you're on. For example, if I wanted the river to be bigger on later floors, I could supply an Arg called RiverSize that the function could use by grabbing it from the Args table.

Now, you'll need to figure out a way to programmatically define your generation step. In our case, we need to figure out how we want to define what constitutes a river. For what Halcyon wanted, the following attributes were needed for the river:
*It takes up about half the map, with its center being around the middle of the dungeon's X axis.
*It flows vertically.
*Its border randomly shifts left and right a few tiles every so often, but not so far as to shift too far from the center.
*Its border never shifts 2 water tiles at a time, or else it may look jagged and strange.
*The left and right borders work independently of each other.
*It doesn't override ground tiles, only wall tiles. This way rooms and hallways are not changed into water.

And with that, we use this and our knowledge of the Lua functions to define an algorithm in event_mapgen.lua that will change wall tiles near the middle of the map into water tiles to simulate a river. Below is some Lua that'll do just that, but you'll need to write something different if you want to do something else:

<pre>
--Halcyon custom map gen steps
--used for making the river in the Illuminant Riverbed
function FLOOR_GEN_SCRIPT.CreateRiver(map, args)
local mapCenter = math.ceil(map.Width / 2)
local randomOffset = map.Rand:Next(-2,3) --a random small offset added to all tiles to help randomize where the river falls a bit
local leftBound = math.floor(mapCenter / 2) + randomOffset --base left bound
local rightBound = math.ceil(mapCenter # 3 / 2) + randomOffset -- base right bound
local leftOffset = map.Rand:Next(-1, 2)
local rightOffset = map.Rand:Next(-1, 2)
local leftShore = 0
local rightShore = 0

local leftOffsetRemaining = map.Rand:Next(1, 5)--how many times this specific offset can be used before being regenerated
local rightOffsetRemaining = map.Rand:Next(1, 5)

--go row by row. Replace ground tiles towards the center of the map with water tiles to create a river flowing through the dungeon.
--Ground tiles will remain untouched. River will ebb a bit side to side within a limit.

for y = 0, map.Height-1, 1 do

--determine starting and ending positions for row of river
--an offset will last for a few rows before trying to roll again for a new offset

--roll new offsets and set new offset timer
--NOTE: map.Rand:Next(lower, upper) is inclusive on lower, and exclusive on upper
if leftOffsetRemaining <= 0 then
if leftOffset < 0 then
leftOffset = map.Rand:Next(-1, 1)
elseif leftOffset > 0 then
leftOffset = map.Rand:Next(0, 2)
else
leftOffset = map.Rand:Next(-1, 2)
end
leftOffsetRemaining = map.Rand:Next(1, 5)
end

if rightOffsetRemaining <= 0 then
if rightOffset < 0 then
rightOffset = map.Rand:Next(-1, 1)
elseif rightOffset > 0 then
rightOffset = map.Rand:Next(0, 2)
else
rightOffset = map.Rand:Next(-1, 2)
end
rightOffsetRemaining = map.Rand:Next(1, 5)
end

leftShore = leftBound + leftOffset
rightShore = rightBound + rightOffset

--set all non ground tiles to water tiles between our left and right bounds
for x = leftShore, rightShore, 1 do
local loc = RogueElements.Loc(x, y)
if not map:GetTile(loc):TileEquivalent(map.RoomTerrain) then
map:TrySetTile(loc, RogueEssence.Dungeon.Tile("water"))
end

end

leftOffsetRemaining = leftOffsetRemaining - 1
rightOffsetRemaining = rightOffsetRemaining - 1

end

end
</pre>

Now that we have our function defined, we need to actually add it to the dungeon floor! This is done by adding it to the gen steps for the floor in the dungeon setup. Where you place it in orderwise depends on what your genstep does, but in our case, it's something that should be ran after all other terrain generation has finished, so we'll put it at priority 4 here. For the Script area, we write the name of our script (in this case, CreateRiver), and define any arguments we may have (in this case, none).

[[File:Custom Gen Step Instructions.PNG|frameless]]

Then, we just load up our floor, and voila! We have a simple but decent looking river now flowing through our dungeon floor!

[[File:2sBVFyb-1-.png|frameless]]

Tutorial:Custom Floor Generation Steps

2023-07-07T00:04:16Z

Palika:

Sometimes, you may find that you want to add a feature to dungeon generation that just isn't possible with built in gen steps and tools. When this happens, you can script the generation step or feature in yourself by scripting via Lua by creating a FLOOR_GEN_SCRIPT in event_mapgen.lua. We'll walk through an example on how this was done for Halcyon's Illuminant Riverbed to show an example of how you can do this and some of the useful Lua functions you might need to do this.

Depending on what exactly you're trying to achieve with your custom gen step, you may want to start with the vanilla gen steps to get a base to work off of, or you may want to start with the Lua customization first. Either way, once you're ready to sit down and work with the Lua scripting, there's some basic functions/knowledge you'll need to know. There are more functions beyond these, but these are all we need for creating a river. You may find additional functions and tools to do things such as creating traps, items, or NPCs in the FLOOR_GEN_SCRIPT.Test function in event_mapgen.lua.

The function that defines your custom gen function should be given two parameters: map and args.
*Map is the floor you're on that you're generating. It includes a number of useful functions and variables such as:
**map.Width: Width of the map
**map.Height: Height of the map
**map.Rand:Next(x, y) - returns a random number, inclusive on lower and exclusive on upper, between x and y. This is important to use instead of math.random so that the dungeon's random seeding is used to generate the random number so replays and such are consistent.
**map:GetTile(loc) - gets the tile at the specified RogueElements.Loc(x,y).
**map:TrySetTile(loc, terrain) - attempts to set the tile at the specified location to the specified terrain type. May fail if the tile should not be changed for some reason (for example, it is the loc of the stairs)

*Args is a list of arguments given in the Arg Table in the ScriptGenStep. Using these, you can write somewhat generic generation algorithms that can be tweaked on a per floor basis by giving different arguments to the function via the genstep's arg table!

Now, we need to figure out how we'd want to go about defining what constitutes our river. In this case, we want the following attributes for our river:
*It takes up about half the map, with its center being around the middle of the dungeon's X axis.
*It flows vertically.
*Its border randomly shifts left and right a few tiles every so often, but not so far as to shift too far from the center.
*Its border never shifts 2 water tiles at a time, or else it may look jagged and strange.
*It doesn't override ground tiles, only wall tiles. This way rooms and hallways are not changed into water.

And with that, we use this and our knowledge of the lua functions to define a function in event_mapgen.lua that will change wall tiles near the middle of the map into water tiles to simulate a river:

--Halcyon custom map gen steps
--used for making the river in the Illuminant Riverbed
function FLOOR_GEN_SCRIPT.CreateRiver(map, args)
local mapCenter = math.ceil(map.Width / 2)
local randomOffset = map.Rand:Next(-2,3) --a random small offset added to all tiles to help randomize where the river falls a bit
local leftBound = math.floor(mapCenter / 2) + randomOffset --base left bound
local rightBound = math.ceil(mapCenter # 3 / 2) + randomOffset -- base right bound
local leftOffset = map.Rand:Next(-1, 2)
local rightOffset = map.Rand:Next(-1, 2)
local leftShore = 0
local rightShore = 0

local leftOffsetRemaining = map.Rand:Next(1, 5)--how many times this specific offset can be used before being regenerated
local rightOffsetRemaining = map.Rand:Next(1, 5)

--go row by row. Replace ground tiles towards the center of the map with water tiles to create a river flowing through the dungeon.
--Ground tiles will remain untouched. River will ebb a bit side to side within a limit.

for y = 0, map.Height-1, 1 do

--determine starting and ending positions for row of river
--an offset will last for a few rows before trying to roll again for a new offset

--roll new offsets and set new offset timer
--NOTE: map.Rand:Next(lower, upper) is inclusive on lower, and exclusive on upper
if leftOffsetRemaining <= 0 then
if leftOffset < 0 then
leftOffset = map.Rand:Next(-1, 1)
elseif leftOffset > 0 then
leftOffset = map.Rand:Next(0, 2)
else
leftOffset = map.Rand:Next(-1, 2)
end
leftOffsetRemaining = map.Rand:Next(1, 5)
end

if rightOffsetRemaining <= 0 then
if rightOffset < 0 then
rightOffset = map.Rand:Next(-1, 1)
elseif rightOffset > 0 then
rightOffset = map.Rand:Next(0, 2)
else
rightOffset = map.Rand:Next(-1, 2)
end
rightOffsetRemaining = map.Rand:Next(1, 5)
end

leftShore = leftBound + leftOffset
rightShore = rightBound + rightOffset

--set all non ground tiles to water tiles between our left and right bounds
for x = leftShore, rightShore, 1 do
local loc = RogueElements.Loc(x, y)
if not map:GetTile(loc):TileEquivalent(map.RoomTerrain) then
map:TrySetTile(loc, RogueEssence.Dungeon.Tile("water"))
end

end

leftOffsetRemaining = leftOffsetRemaining - 1
rightOffsetRemaining = rightOffsetRemaining - 1

end

end

Now that we have our function defined, we need to actually add it to the dungeon floor! This is done by adding it to the gen steps for the floor in the dungeon setup. Where you place it in orderwise depends on what your genstep does, but in our case, it's something that should be ran after all other terrain generation has finished, so we'll put it at priority 4 here. For the Script area, we write the name of our script (in this case, CreateRiver), and define any arguments we may have (in this case, none).

[[File:Custom Gen Step Instructions.PNG|frameless]]

Then, we just load up our floor, and voila! We have a simple but decent looking river now flowing through our dungeon floor!

[[File:2sBVFyb-1-.png|frameless]]

Tutorial:Custom Floor Generation Steps

2023-07-06T18:11:50Z

Palika:

Sometimes, you may find that you want to add a feature to dungeon generation that just isn't possible with built in gen steps and tools. When this happens, you can script the generation step or feature in yourself by scripting via Lua by creating a FLOOR_GEN_SCRIPT in event_mapgen.lua. We'll walk through an example on how this was done for Halcyon's Illuminant Riverbed to show an example of how you can do this and some of the useful Lua functions you might need to do this.

Depending on what exactly you're trying to achieve with your custom gen step, you may want to start with the vanilla gen steps to get a base to work off of, or you may want to start with the Lua customization first. Either way, once you're ready to sit down and work with the Lua scripting, there's some basic functions/knowledge you'll need to know. There are more functions beyond these, but these are all we need for creating a river. You may find additional functions and tools to do things such as creating traps, items, or NPCs in the FLOOR_GEN_SCRIPT.Test function in event_mapgen.lua.

The function that defines your custom gen function should be given two parameters: map and args.
Map is the floor you're on that you're generating. It includes a number of useful functions and variables such as:
* map.Width: Width of the map
* map.Height: Height of the map
* map.Rand:Next(x, y) - returns a random number, inclusive on lower and exclusive on upper, between x and y. This is important to use instead of math.random so that the dungeon's random seeding is used to generate the random number so replays and such are consistent.
* map:GetTile(loc) - gets the tile at the specified RogueElements.Loc(x,y).
* map:TrySetTile(loc, terrain) - attempts to set the tile at the specified location to the specified terrain type. May fail if the tile should not be changed for some reason (for example, it is the loc of the stairs)

Args is a list of arguments given in the Arg Table in the ScriptGenStep. Using these, you can write somewhat generic generation algorithms that can be tweaked on a per floor basis by giving different arguments to the function via the genstep's arg table!

Now, we need to figure out how we'd want to go about defining what constitutes our river. In this case, we want the following attributes for our river:
* It takes up about half the map, with its center being around the middle of the dungeon's X axis.
* It flows vertically.
* Its border randomly shifts left and right a few tiles every so often, but not so far as to shift too far from the center.
* Its border never shifts 2 water tiles at a time, or else it may look jagged and strange.
* It doesn't override ground tiles, only wall tiles. This way rooms and hallways are not changed into water.

And with that, we use this and our knowledge of the lua functions to define a function in event_mapgen.lua that will change wall tiles near the middle of the map into water tiles to simulate a river:

--Halcyon custom map gen steps
--used for making the river in the Illuminant Riverbed
function FLOOR_GEN_SCRIPT.CreateRiver(map, args)
local mapCenter = math.ceil(map.Width / 2)
local randomOffset = map.Rand:Next(-2,3) --a random small offset added to all tiles to help randomize where the river falls a bit
local leftBound = math.floor(mapCenter / 2) + randomOffset --base left bound
local rightBound = math.ceil(mapCenter * 3 / 2) + randomOffset -- base right bound
local leftOffset = map.Rand:Next(-1, 2)
local rightOffset = map.Rand:Next(-1, 2)
local leftShore = 0
local rightShore = 0

local leftOffsetRemaining = map.Rand:Next(1, 5)--how many times this specific offset can be used before being regenerated
local rightOffsetRemaining = map.Rand:Next(1, 5)

--go row by row. Replace ground tiles towards the center of the map with water tiles to create a river flowing through the dungeon.
--Ground tiles will remain untouched. River will ebb a bit side to side within a limit.

for y = 0, map.Height-1, 1 do

--determine starting and ending positions for row of river
--an offset will last for a few rows before trying to roll again for a new offset

--roll new offsets and set new offset timer
--NOTE: map.Rand:Next(lower, upper) is inclusive on lower, and exclusive on upper
if leftOffsetRemaining <= 0 then
if leftOffset < 0 then
leftOffset = map.Rand:Next(-1, 1)
elseif leftOffset > 0 then
leftOffset = map.Rand:Next(0, 2)
else
leftOffset = map.Rand:Next(-1, 2)
end
leftOffsetRemaining = map.Rand:Next(1, 5)
end

if rightOffsetRemaining <= 0 then
if rightOffset < 0 then
rightOffset = map.Rand:Next(-1, 1)
elseif rightOffset > 0 then
rightOffset = map.Rand:Next(0, 2)
else
rightOffset = map.Rand:Next(-1, 2)
end
rightOffsetRemaining = map.Rand:Next(1, 5)
end

leftShore = leftBound + leftOffset
rightShore = rightBound + rightOffset

--set all non ground tiles to water tiles between our left and right bounds
for x = leftShore, rightShore, 1 do
local loc = RogueElements.Loc(x, y)
if not map:GetTile(loc):TileEquivalent(map.RoomTerrain) then
map:TrySetTile(loc, RogueEssence.Dungeon.Tile("water"))
end

end

leftOffsetRemaining = leftOffsetRemaining - 1
rightOffsetRemaining = rightOffsetRemaining - 1

end

end

Now that we have our function defined, we need to actually add it to the dungeon floor! This is done by adding it to the gen steps for the floor in the dungeon setup. Where you place it in orderwise depends on what your genstep does, but in our case, it's something that should be ran after all other terrain generation has finished, so we'll put it at priority 4 here. For the Script area, we write the name of our script (in this case, CreateRiver), and define any arguments we may have (in this case, none).

[[File:Custom Gen Step Instructions.PNG|frameless]]

Then, we just load up our floor, and voila! We have a simple but decent looking river now flowing through our dungeon floor!

Tutorial:Custom Floor Generation Steps

2023-07-06T18:09:40Z

Palika:

Sometimes, you may find that you want to add a feature to dungeon generation that just isn't possible with built in gen steps and tools. When this happens, you can script the generation step or feature in yourself by scripting via Lua by creating a FLOOR_GEN_SCRIPT in event_mapgen.lua. We'll walk through an example on how this was done for Halcyon's Illuminant Riverbed to show an example of how you can do this and some of the useful Lua functions you might need to do this.

Depending on what exactly you're trying to achieve with your custom gen step, you may want to start with the vanilla gen steps to get a base to work off of, or you may want to start with the Lua customization first. Either way, once you're ready to sit down and work with the Lua scripting, there's some basic functions/knowledge you'll need to know. There are more functions beyond these, but these are all we need for creating a river. You may find additional functions and tools to do things such as creating traps, items, or NPCs in the FLOOR_GEN_SCRIPT.Test function in event_mapgen.lua.

The function that defines your custom gen function should be given two parameters: map and args.
Map is the floor you're on that you're generating. It includes a number of useful functions and variables such as:
* map.Width: Width of the map
* map.Height: Height of the map
* map.Rand:Next(x, y) - returns a random number, inclusive on lower and exclusive on upper, between x and y. This is important to use instead of math.random so that the dungeon's random seeding is used to generate the random number so replays and such are consistent.
* map:GetTile(loc) - gets the tile at the specified RogueElements.Loc(x,y).
* map:TrySetTile(loc, terrain) - attempts to set the tile at the specified location to the specified terrain type. May fail if the tile should not be changed for some reason (for example, it is the loc of the stairs)

Args is a list of arguments given in the Arg Table in the ScriptGenStep. Using these, you can write somewhat generic generation algorithms that can be tweaked on a per floor basis by giving different arguments to the function via the genstep's arg table!

Now, we need to figure out how we'd want to go about defining what constitutes our river. In this case, we want the following attributes for our river:
* It takes up about half the map, with its center being around the middle of the dungeon's X axis.
* It flows vertically.
* Its border randomly shifts left and right a few tiles every so often, but not so far as to shift too far from the center.
* Its border never shifts 2 water tiles at a time, or else it may look jagged and strange.
* It doesn't override ground tiles, only wall tiles. This way rooms and hallways are not changed into water.

And with that, we use this and our knowledge of the lua functions to define a function in event_mapgen.lua that will change wall tiles near the middle of the map into water tiles to simulate a river:

--Halcyon custom map gen steps
--used for making the river in the Illuminant Riverbed
function FLOOR_GEN_SCRIPT.CreateRiver(map, args)
local mapCenter = math.ceil(map.Width / 2)
local randomOffset = map.Rand:Next(-2,3) --a random small offset added to all tiles to help randomize where the river falls a bit
local leftBound = math.floor(mapCenter / 2) + randomOffset --base left bound
local rightBound = math.ceil(mapCenter * 3 / 2) + randomOffset -- base right bound
local leftOffset = map.Rand:Next(-1, 2)
local rightOffset = map.Rand:Next(-1, 2)
local leftShore = 0
local rightShore = 0

local leftOffsetRemaining = map.Rand:Next(1, 5)--how many times this specific offset can be used before being regenerated
local rightOffsetRemaining = map.Rand:Next(1, 5)

--go row by row. Replace ground tiles towards the center of the map with water tiles to create a river flowing through the dungeon.
--Ground tiles will remain untouched. River will ebb a bit side to side within a limit.

for y = 0, map.Height-1, 1 do

--determine starting and ending positions for row of river
--an offset will last for a few rows before trying to roll again for a new offset

--roll new offsets and set new offset timer
--NOTE: map.Rand:Next(lower, upper) is inclusive on lower, and exclusive on upper
if leftOffsetRemaining <= 0 then
if leftOffset < 0 then
leftOffset = map.Rand:Next(-1, 1)
elseif leftOffset > 0 then
leftOffset = map.Rand:Next(0, 2)
else
leftOffset = map.Rand:Next(-1, 2)
end
leftOffsetRemaining = map.Rand:Next(1, 5)
end

if rightOffsetRemaining <= 0 then
if rightOffset < 0 then
rightOffset = map.Rand:Next(-1, 1)
elseif rightOffset > 0 then
rightOffset = map.Rand:Next(0, 2)
else
rightOffset = map.Rand:Next(-1, 2)
end
rightOffsetRemaining = map.Rand:Next(1, 5)
end

leftShore = leftBound + leftOffset
rightShore = rightBound + rightOffset

--set all non ground tiles to water tiles between our left and right bounds
for x = leftShore, rightShore, 1 do
local loc = RogueElements.Loc(x, y)
if not map:GetTile(loc):TileEquivalent(map.RoomTerrain) then
map:TrySetTile(loc, RogueEssence.Dungeon.Tile("water"))
end

end

leftOffsetRemaining = leftOffsetRemaining - 1
rightOffsetRemaining = rightOffsetRemaining - 1

end

end

Now that we have our function defined, we need to actually add it to the dungeon floor! This is done by adding it to the gen steps for the floor in the dungeon setup. Where you place it in orderwise depends on what your genstep does, but in our case, it's something that should be ran after all other terrain generation has finished, so we'll put it at priority 4 here. For the Script area, we write the name of our script (in this case, CreateRiver), and define any arguments we may have (in this case, none).

[[File:Custom Gen Step Instructions.png|frameless]]

Then, we just load up our floor, and voila! We have a simple but decent looking river now flowing through our dungeon floor!

File:Custom Gen Step Instructions.PNG

2023-07-06T18:09:04Z

Palika: Uploaded with SimpleBatchUpload

File:FOWyQRU-1-.png

2023-07-06T18:07:24Z

Palika: Uploaded with SimpleBatchUpload

File:2sBVFyb-1-.png

2023-07-06T18:07:16Z

Palika: Uploaded with SimpleBatchUpload

Tutorial:Custom Floor Generation Steps

2023-07-06T18:01:49Z

Palika:

Sometimes, you may find that you want to add a feature to dungeon generation that just isn't possible with built in gen steps and tools. When this happens, you can script the generation step or feature in yourself by scripting via Lua by creating a FLOOR_GEN_SCRIPT in event_mapgen.lua. We'll walk through an example on how this was done for Halcyon's Illuminant Riverbed to show an example of how you can do this and some of the useful Lua functions you might need to do this.

Depending on what exactly you're trying to achieve with your custom gen step, you may want to start with the vanilla gen steps to get a base to work off of, or you may want to start with the Lua customization first. Either way, once you're ready to sit down and work with the Lua scripting, there's some basic functions/knowledge you'll need to know. There are more functions beyond these, but these are all we need for creating a river. You may find additional functions and tools to do things such as creating traps, items, or NPCs in the FLOOR_GEN_SCRIPT.Test function in event_mapgen.lua.

The function that defines your custom gen function should be given two parameters: map and args.
Map is the floor you're on that you're generating. It includes a number of useful functions and variables such as:
* map.Width: Width of the map
* map.Height: Height of the map
* map.Rand:Next(x, y) - returns a random number, inclusive on lower and exclusive on upper, between x and y. This is important to use instead of math.random so that the dungeon's random seeding is used to generate the random number so replays and such are consistent.
* map:GetTile(loc) - gets the tile at the specified RogueElements.Loc(x,y).
* map:TrySetTile(loc, terrain) - attempts to set the tile at the specified location to the specified terrain type. May fail if the tile should not be changed for some reason (for example, it is the loc of the stairs)

Args is a list of arguments given in the Arg Table in the ScriptGenStep. Using these, you can write somewhat generic generation algorithms that can be tweaked on a per floor basis by giving different arguments to the function via the genstep's arg table!

Now, we need to figure out how we'd want to go about defining what constitutes our river. In this case, we want the following attributes for our river:
* It takes up about half the map, with its center being around the middle of the dungeon's X axis.
* It flows vertically.
* Its border randomly shifts left and right a few tiles every so often, but not so far as to shift too far from the center.
* Its border never shifts 2 water tiles at a time, or else it may look jagged and strange.
* It doesn't override ground tiles, only wall tiles. This way rooms and hallways are not changed into water.

And with that, we use this and our knowledge of the lua functions to define a function in event_mapgen.lua that will change wall tiles near the middle of the map into water tiles to simulate a river:

--Halcyon custom map gen steps
--used for making the river in the Illuminant Riverbed
function FLOOR_GEN_SCRIPT.CreateRiver(map, args)
local mapCenter = math.ceil(map.Width / 2)
local randomOffset = map.Rand:Next(-2,3) --a random small offset added to all tiles to help randomize where the river falls a bit
local leftBound = math.floor(mapCenter / 2) + randomOffset --base left bound
local rightBound = math.ceil(mapCenter * 3 / 2) + randomOffset -- base right bound
local leftOffset = map.Rand:Next(-1, 2)
local rightOffset = map.Rand:Next(-1, 2)
local leftShore = 0
local rightShore = 0

local leftOffsetRemaining = map.Rand:Next(1, 5)--how many times this specific offset can be used before being regenerated
local rightOffsetRemaining = map.Rand:Next(1, 5)

--go row by row. Replace ground tiles towards the center of the map with water tiles to create a river flowing through the dungeon.
--Ground tiles will remain untouched. River will ebb a bit side to side within a limit.

for y = 0, map.Height-1, 1 do

--determine starting and ending positions for row of river
--an offset will last for a few rows before trying to roll again for a new offset

--roll new offsets and set new offset timer
--NOTE: map.Rand:Next(lower, upper) is inclusive on lower, and exclusive on upper
if leftOffsetRemaining <= 0 then
if leftOffset < 0 then
leftOffset = map.Rand:Next(-1, 1)
elseif leftOffset > 0 then
leftOffset = map.Rand:Next(0, 2)
else
leftOffset = map.Rand:Next(-1, 2)
end
leftOffsetRemaining = map.Rand:Next(1, 5)
end

if rightOffsetRemaining <= 0 then
if rightOffset < 0 then
rightOffset = map.Rand:Next(-1, 1)
elseif rightOffset > 0 then
rightOffset = map.Rand:Next(0, 2)
else
rightOffset = map.Rand:Next(-1, 2)
end
rightOffsetRemaining = map.Rand:Next(1, 5)
end

leftShore = leftBound + leftOffset
rightShore = rightBound + rightOffset

--set all non ground tiles to water tiles between our left and right bounds
for x = leftShore, rightShore, 1 do
local loc = RogueElements.Loc(x, y)
if not map:GetTile(loc):TileEquivalent(map.RoomTerrain) then
map:TrySetTile(loc, RogueEssence.Dungeon.Tile("water"))
end

end

leftOffsetRemaining = leftOffsetRemaining - 1
rightOffsetRemaining = rightOffsetRemaining - 1

end

end

Now that we have our function defined, we need to actually add it to the dungeon floor! This is done by adding it to the gen steps for the floor in the dungeon setup. Where you place it in orderwise depends on what your genstep does, but in our case, it's something that should be ran after all other terrain generation has finished, so we'll put it at priority 4 here. For the Script area, we write the name of our script (in this case, CreateRiver), and define any arguments we may have (in this case, none).

[EDITOR PICTURE HERE]

Then, we just load up our floor, and voila! We have a simple but decent looking river now flowing through our dungeon floor!

Tutorial:Custom Floor Generation Steps

2023-07-06T18:01:10Z

Palika: Created page with "Sometimes, you may find that you want to add a feature to dungeon generation that just isn't possible with built in gen steps and tools. When this happens, you can script the generation step or feature in yourself by scripting via Lua by creating a FLOOR_GEN_SCRIPT in event_mapgen.lua. We'll walk through an example on how this was done for Halcyon's Illuminant Riverbed to show an example of how you can do this and some of the useful Lua functions you might need to do thi..."

Sometimes, you may find that you want to add a feature to dungeon generation that just isn't possible with built in gen steps and tools. When this happens, you can script the generation step or feature in yourself by scripting via Lua by creating a FLOOR_GEN_SCRIPT in event_mapgen.lua. We'll walk through an example on how this was done for Halcyon's Illuminant Riverbed to show an example of how you can do this and some of the useful Lua functions you might need to do this.

Depending on what exactly you're trying to achieve with your custom gen step, you may want to start with the vanilla gen steps to get a base to work off of, or you may want to start with the Lua customization first. Either way, once you're ready to sit down and work with the Lua scripting, there's some basic functions/knowledge you'll need to know. There are more functions beyond these, but these are all we need for creating a river. You may find additional functions and tools to do things such as creating traps, items, or NPCs in the FLOOR_GEN_SCRIPT.Test function in event_mapgen.lua.

* The function that defines your custom gen function should be given two parameters: map and args.
* map is the floor you're on that you're generating. It includes a number of useful functions and variables such as:
* map.Width: Width of the map
* map.Height: Height of the map
* map.Rand:Next(x, y) - returns a random number, inclusive on lower and exclusive on upper, between x and y. This is important to use instead of math.random so that the dungeon's random seeding is used to generate the random number so replays and such are consistent.
* map:GetTile(loc) - gets the tile at the specified RogueElements.Loc(x,y).
* map:TrySetTile(loc, terrain) - attempts to set the tile at the specified location to the specified terrain type. May fail if the tile should not be changed for some reason (for example, it is the loc of the stairs)

* args is a list of arguments given in the Arg Table in the ScriptGenStep. Using these, you can write somewhat generic generation algorithms that can be tweaked on a per floor basis by giving different arguments to the function via the genstep's arg table!

Now, we need to figure out how we'd want to go about defining what constitutes our river. In this case, we want the following attributes for our river:
* It takes up about half the map, with its center being around the middle of the dungeon's X axis.
* It flows vertically.
* Its border randomly shifts left and right a few tiles every so often, but not so far as to shift too far from the center.
* Its border never shifts 2 water tiles at a time, or else it may look jagged and strange.
* It doesn't override ground tiles, only wall tiles. This way rooms and hallways are not changed into water.

And with that, we use this and our knowledge of the lua functions to define a function in event_mapgen.lua that will change wall tiles near the middle of the map into water tiles to simulate a river:

--Halcyon custom map gen steps
--used for making the river in the Illuminant Riverbed
function FLOOR_GEN_SCRIPT.CreateRiver(map, args)
local mapCenter = math.ceil(map.Width / 2)
local randomOffset = map.Rand:Next(-2,3) --a random small offset added to all tiles to help randomize where the river falls a bit
local leftBound = math.floor(mapCenter / 2) + randomOffset --base left bound
local rightBound = math.ceil(mapCenter * 3 / 2) + randomOffset -- base right bound
local leftOffset = map.Rand:Next(-1, 2)
local rightOffset = map.Rand:Next(-1, 2)
local leftShore = 0
local rightShore = 0

local leftOffsetRemaining = map.Rand:Next(1, 5)--how many times this specific offset can be used before being regenerated
local rightOffsetRemaining = map.Rand:Next(1, 5)

--go row by row. Replace ground tiles towards the center of the map with water tiles to create a river flowing through the dungeon.
--Ground tiles will remain untouched. River will ebb a bit side to side within a limit.

for y = 0, map.Height-1, 1 do

--determine starting and ending positions for row of river
--an offset will last for a few rows before trying to roll again for a new offset

--roll new offsets and set new offset timer
--NOTE: map.Rand:Next(lower, upper) is inclusive on lower, and exclusive on upper
if leftOffsetRemaining <= 0 then
if leftOffset < 0 then
leftOffset = map.Rand:Next(-1, 1)
elseif leftOffset > 0 then
leftOffset = map.Rand:Next(0, 2)
else
leftOffset = map.Rand:Next(-1, 2)
end
leftOffsetRemaining = map.Rand:Next(1, 5)
end

if rightOffsetRemaining <= 0 then
if rightOffset < 0 then
rightOffset = map.Rand:Next(-1, 1)
elseif rightOffset > 0 then
rightOffset = map.Rand:Next(0, 2)
else
rightOffset = map.Rand:Next(-1, 2)
end
rightOffsetRemaining = map.Rand:Next(1, 5)
end

leftShore = leftBound + leftOffset
rightShore = rightBound + rightOffset

--set all non ground tiles to water tiles between our left and right bounds
for x = leftShore, rightShore, 1 do
local loc = RogueElements.Loc(x, y)
if not map:GetTile(loc):TileEquivalent(map.RoomTerrain) then
map:TrySetTile(loc, RogueEssence.Dungeon.Tile("water"))
end

end

leftOffsetRemaining = leftOffsetRemaining - 1
rightOffsetRemaining = rightOffsetRemaining - 1

end

end

Now that we have our function defined, we need to actually add it to the dungeon floor! This is done by adding it to the gen steps for the floor in the dungeon setup. Where you place it in orderwise depends on what your genstep does, but in our case, it's something that should be ran after all other terrain generation has finished, so we'll put it at priority 4 here. For the Script area, we write the name of our script (in this case, CreateRiver), and define any arguments we may have (in this case, none).

[EDITOR PICTURE HERE]

Then, we just load up our floor, and voila! We have a simple but decent looking river now flowing through our dungeon floor!