modernReserveItems.lua v2.0 - SM3DL/SM3DW reserve mechanics

[KBM-Quine]

credits to the following for massive amounts of code help: rixithechao, Enjl, Hoeloe, PixelPest, and MrDoubleA. as well as Hoeloe and Rednaxela for work taken from npcconnpcconfig_core.lua.
as you'd guess from the title, this aims to make the reserve box function like it does in SM3DL/SM3DW, with some added SMBX mannerisms.
such as:

• items default to being held (barring some already defined exceptions)
• auto held when first spawned (configurable)
• if riding yoshi, any holdable items are placed in yoshis mouth. (given yoshi can eat them in the first place)
• if in a clowncar, it spawns the npc on the players car on the side the player is facing.
• can spawn a holdable item while warping, only if the warp allows items.
• near every aspect is configurable. (see documentation for more)

some scenarios where the player can't use the reserve box:

scenarios: show

• in in the overworld.
• if in a launch barrel.
• all forced animation states. (aside from warping/using a clearpipe) all states can be found here.
• if a warp doesn't allow items or modernReserveItems.allowHeldItemsInWarps is false.
• is climbing on a vine. (held only)
• yoshi can't usually eat the item (held only)
• if yoshi's mouth is full. (held only)
• if mounted in a boot. (held only)
• if the player's hands are full. (held only)
• if using the tanooki statue. (held only)
• if currently dead.
• if the level is considered won.
• if any of the "modernReserveItems.allowX" options are false (per-case basis)

this mainly came about as a accessibility option for DA:E, but upon thinking about the best implementation, i figured others may also like said feature.
here's a showcase video for all the action:https://streamable.com/whte3v

how to use & documentation: show

this section assumes you have some knowledge of lunalua/lua. if not, then the only thing you need is the next two lines.
to start, use this to load it

Code: Select all

local modernReserveItems = require("modernReserveItems")

after which you can be on your way if your content with the default settings.
but if you'd rather do some tinkering, here's a breakdown of how to do so for individual npcs:

Code: Select all

modernReserveItems.config[1].isHeld = false
modernReserveItems.config[1].isThrowm = true

this will make smb3 goombas thrown rather then held when dropped. there is a function for seting multiple at once as well:

Code: Select all

modernReserveItems.setConfigs(npcID, {speedX=number, speedY=number, isHeld=bool, forcedState=number, isThrown=bool, doesntMove=bool, sfx=number or string of sound file, yoshiSFX=number or string of sound file, idOverwrite=number, ai1-ai6=number, data={variable=value}})

(not every value needs to be set here)
let's go over all that:

• npcID - fill this with the npc ID you want to change the settings for.
• speedX/speedY - sets the speedX/Y upon it's spawn.
• isHeld - is used to determine if the item should be held upon spawning it. set to false if you intend to use one of the two other flags to determine behavior.
• forcedState - (currently only used by the reserve stopwatch) is used to determine misc behavior upon spawning it. see this page for more details on NPC forcedStates.
• isThrown - is used to determine if the item should be thrown upon spawning it. set to false if you intend to use one of the two other flags to determine behavior.
• doesntMove - (only applies to isThrown items.) if the item should not move upon spawning. sets the projectile flag for this to work properly, may lead to accidental npc kills. you have been warned.
• sfx - the sound played upon the npc's spawn. does not play if modernReserveItems.playSounds is false, also doesn't play a sound for isContained items.
• yoshiSFX - the sound played upon a held npc's spawn while riding yoshi. does not play if modernReserveItems.playSounds is false.
• idOverwrite - changes the id of the spawned npc. good for container npcs. (currently only used for proper yoshi spawning. lest we forget...)
• ai1-ai6 - the ai values to be set upon spawning. see this page for more information.
• data - variables to set in the npc's data fields upon spawn. (not used by anything predefined, mainly added for the neatness of the feature)

available library variables:

• modernReserveItems.enabled - bool;whether or not the library is allowed to run. good for making it an optional setting. true by default.
• modernReserveItems.autoHold - bool;if the library is allowed to auto hold the run button for a short time after spawning isHeld npcs. true by default.
• modernReserveItems.timeAutoHeld- number;how long AutoHold will hold npcs in enabled. 32 by default.
• modernReserveItems.playSounds - bool;if the library should play sounds upon spawning npcs. true by default.
• modernReserveItems.playerXMomentum/modernReserveItems.playerYMomentum - number;how much to times the player's speedX/speedY by before adding it to the spawned npc's speedX/speedY. i recommend decimal numbers, such as 0.5 or so. 0 by default.
• modernReserveItems.allowThrownItems - bool;a flag to disable thrown items from being spawned. good for user edge cases. true by default.
• modernReserveItems.allowHeldItems - bool;a flag to disable held items from being spawned. good for user edge cases. true by default.
• modernReserveItems.allowHeldItemsInWarps- bool;a flag to disable held items from being spawned in warps/clearpipes. good for user edge cases. true by default.
• modernReserveItems.allowForcedStateItems - bool;a flag to disable forcedStateitems from being spawned. good for user edge cases. true by default.
• modernReserveItems.allowAnyItems - bool;a flag to disable all items from being spawned. good for user edge cases. true by default.
• modernReserveItems.spawnLayer - string;determines what layer the npc is given on spawn. "Spawned NPCs" by default.
• modernReserveItems.useBuiltInDrop - bool;a third flag that gets checked alongside modernReserveItems.enabled and isOverworld. good for systems where you need to use modernReserveItems.drop without changing modernReserveItems.enabled. true by default.
• modernReserveItems.offScreenDespawn - number;determines how many ticks the npc can be offscreen before being despawned. 3600 (or 60 seconds) by default.

available library functions:

• modernReserveItems.drop(npcID, p) - function;used to spawn a reserve item. can be used to integrate modernReserveItems's system into external ones. returns the spawned NPC reference or nil if failed. will require modernReserveItems to be loaded in the same file to use.
  - npcID - npc ID (intended for player.reservePowerup)
  - p - player object.
• modernReserveItems.validityCheck(npcID, p) - function;used to resolve conditions which .drop() can be used. can also allow external libraries to check the conditions without needing to recreate them. returns false upon meeting any criteria in it, otherwise returns true. see scenarios spoiler for details. will require modernReserveItems to be loaded in the same file to use.
  - npcID - npc ID (intended for player.reservePowerup)
  - p - player object.
• modernReserveItems.onReserveUse(eventObj, npcID, p) - function; used to run code upon modernReserveItems.drop being called. will require modernReserveItems to be loaded in the same file to use.
  - eventObj - used as any other lua event object. doing eventObj.cancelled = true will cause modernReserveItems.drop to abort and return nil.
  - npcID - the current ID being used by modernReserveItems.drop
  - p - the current player object being used by modernReserveItems.drop
  Example code is included in the download as testLib.lua.
• modernReserveItems.onPostReserveUse(npc, p) - function;runs after modernReserveItems.drop successfully executes. npc being the npc resulting from modernReserveItems.drop and p the player object it was using. will require modernReserveItems to be loaded in the same file to use.
  - npc - npc object resulting from a successful drop
  - p - player object.

known bugs: show

N/A

changelog: show

-- v1.2 (2/18/2023) --

• fixed a mass typo of "pattren".
• made it use onInputUpdate instead of onTick. preeettty sure that won't change anything...
• adjusted items being spawned whilst riding yoshi. fixing yoshi ducking/opening their mouth for a frame.
• renamed the npc variable for modernReserveItems.drop from "spawned" to "MRINPC". was having issues with other npc variables of the same name somehow referencing it.
• added modernReserveItems.spawnLayer (string). see the documentation for more info.
• moved all validity checking to modernReserveItems.validityCheck(ID, p). see the documentation for more info.
  - now checks if the player's dead or if the game is in a winning state as well.
• modernReserveItems.drop(ID, p) now returns nil on an event cancel from modernReserveItems.onReserveUse (see documentation) or the npc object it spawns.
• added modernReserveItems.onReserveUse(eventObj, ID, p, throwSettings). see the documentation for more info.
• added modernReserveItems.onPostReserveUse(npc, p). npc being the npc resulting from modernReserveItems.drop and p the player object. see the documentation for more info.
• modernReserveItems.resolveThrowSettings(npcID, field) is now usable by external sources. see the documentation for more info.

-- v1.3 (6/2/2023) --

• added modernReserveItems.useBuiltInDrop (bool). see the documentation for more info.
• added modernReserveItems.offScreenDespawn (number). see the documentation for more info.
• adjusted item coordinates calulations, fixing a few oddities with using reserve items on mounts.
  - this causes isMega to become unused. it is now left in for users instead.
• added an entire system to handle projectile npcs killing other npcs, fixing powerups dying to what ever is in their way. (lightly tested;may have missed edge case.)
• fixed up original post and added more documentation.

-- v2.0 (4/14/2024) --

• rebuilt/took config system from npcconfig_core.lua. this reduces alot of repeat code.
• patterns have been completely removed as a result of the config system overhaul.
• resolveThrowSettings has been removed due to config overhaul as well.
• removed an unnecessary loop for warp checking.
• more code comments (for personal rememberance).
• any mem addresses that have field equivalents in B5 have been updated.
• isMega has been completely removed.
• isContained & containedID have been combined into one config, forcedState.
• allowContainedItems has been renamed allowForcedStateItems as following the config renamed
• isEgg has been replaced by idOverwrite. useful for container npcs.
• SFX has been renamed to sfx.
• the ai config table has been separated into indivdual ai# fields (1-6).
• onReserveUse has lost the throwSettings argument following config overhaul.
• fixed onPostReserveUse not returning the resulting npc from .drop
• onReserveUse and onPostReserveUse have been made to work across mulitle lua files (see included example materials for how)

included in the download is example material and offline docs & changelog (just some txt files).
feel free to suggest things, bug report, or what have you. have a nice day.

[FireSeraphim]

This is exactly what I needed!

[Jumper]

Nice! I'm surprised we didn't get this yet, as it's very useful in general.

There's something that I'd like to see added in SMBX 2.0, and it's Mystery Boxes and its variants, though I'm not going to rush anyone to fulfill this, especially on this post.

Regardless, thanks for making this; this will definitely be helpful for Episodes!

[KBM-Quine]

updated with reduced repeat code, changes, fixes, and added features. i must thank MrDoubleA for helping workshop it + the pause bug he found. you can read more about these in the original post, but here's a list of added things:

• modernReserveItems.timeAutoHeld
• modernReserveItems.allowHeldItemsInWarps
• isThrown
• containedID
• doesntMove

the mushroom pattern has had doesntMove set to true by default. if you want the old mushroom pattern behavior, drop these lines where applicable:

Code: Select all

modernReserveItems.patterns.mushroom.speedX = 0.5
modernReserveItems.patterns.mushroom.doesntMove = false

[KBM-Quine]

small update:
default fields weren't being appended properly if an item had an existing pattern, should be fixed. download updated.
this should now allow you to give npcs spawned by modernReserverItems data fields via the default pattern. useful for manipulating npcs on the fly.

[Marioman2007]

ping

It's quite difficult to use the modernReserveItems.drop function properly. Since there's no way to check if the npc spawned correctly due to the 14 returns in the function.
One idea would be to return the spawned npc so users can check if it's nil or not, that'd also help to store a reference to use it later.

The case in which I want to use the function is for a custom reserve item lib, but since I can't check if the function spawned the npc or not, I can't set the custom reserve item to 0 without modifying modernReserveItems.lua directly.

Thanks for listening!

[KBM-Quine]

update to address the above. fixed, tweaked, and added some things. which brings us up to version 1.2. due to server errors, i can't update the OP's text (but i can update the download lol). so this'll have to do:

changelog: show

-- v1.2 (2/18/2023) --

• fixed a mass typo of "pattren".
• made it use onInputUpdate instead of onTick. preeettty sure that won't change anything...
• adjusted items being spawned whilst riding yoshi. fixing yoshi ducking/opening their mouth for a frame.
• renamed the npc variable for modernReserveItems.drop from "spawned" to "MRINPC". was having issues with other npc variables of the same name somehow referencing it.
• added modernReserveItems.spawnLayer (string). see the documentation spoiler for more info.
• moved all validity checking to modernReserveItems.validityCheck(ID, p). see the documentation spoiler for more info.
  - now checks if the player's dead or if the game is in a winning state as well.
• modernReserveItems.drop(ID, p) now returns nil on an event cancel from modernReserveItems.onReserveUse (more in a moment) or the npc object it spawns.
• added modernReserveItems.onReserveUse(eventObj, ID, p, throwSettings). see the documentation spoiler for more info.
• added modernReserveItems.onPostReserveUse(npc, p). npc being the npc resulting from modernReserveItems.drop and p the player object. see the documentation spoiler for more info.
• modernReserveItems.resolveThrowSettings(npcID, field) is now usable by external sources. see the documentation spoiler for more info.

documentation: show

• modernReserveItems.spawnLayer - string;determines what layer the npc is given on spawn. "Spawned NPCs" by default.
• modernReserveItems.validityCheck(ID, p) - function;can be used to allow external libraries the freedom to use modernReserveItems.drop without it failing due to builtin checks or use it to abide by them. returns false upon meeting any criteria in it, otherwise returns true. will require modernReserveItems to be loaded in the same file to use.
  - ID - npc ID (intended for player.reservePowerup)
  - p - player object.
• modernReserveItems.onReserveUse(eventObj, ID, p, throwSettings) - function; used to run code upon modernReserveItems.drop being called. will require modernReserveItems to be loaded in the same file to use.
  - eventObj - used as any other lua event object. doing eventObj.cancelled = true will cause modernReserveItems.drop to abort and return nil.
  - ID - the current ID being used by modernReserveItems.drop
  - p - the current player object being used by modernReserveItems.drop
  - throwSettings - a resolved throw settings table currently being used by modernReserveItems.drop. includes: .speedX, .speedY, .isHeld, .isContained, .isThrown, .containedID, .isMega, .doesntMove, .isEgg, .data, .ai, .SFX, .yoshiSFX.
  below is example code & a gif of that in action:
  example: show

  Code: Select all

  local modernReserveItems = require("modernReserveItems")
  
  modernReserveItems.onReserveUse(eventObj, ID, p , throwSettings)
      if ID == 153 then
          eventObj.cancelled = true -- makes modernReserveItems.drop abort
          for i=0,5 do
              local n = NPC.spawn(10, p.x + p.width*0.5, p.y + p.height*0.5)
              n.speedY = -6 - (0.2*i)
              n.speedX = -1.3 + (0.3*i)
              Defines.earthquake = 20
              n.ai1 = 1 -- gives coins gravity
              n:mem(0x136, FIELD_BOOL, true) -- thrown/projectile flag
          end
          p.reservePowerup = 0 
          p:kill()
      end
  end

  
• modernReserveItems.onPostReserveUse(npc, p) - function;runs after modernReserveItems.drop successfully executes. npc being the npc resulting from modernReserveItems.drop and p the player object it was using. will require modernReserveItems to be loaded in the same file to use.
• modernReserveItems.resolveThrowSettings(npcID, field) - function; returns the resolved setting specified. field being a string (so it'd be used like modernReserveItems.resolveThrowSettings(ID, "isContained"), ect.) intended to be used with modernReserveItems.onReserveUse or alike functions. will require modernReserveItems to be loaded in the same file to use.

download in op updated.

[KBM-Quine]

small update with a largely requested fix and 2 new variables to customize. see the op changelog for details.

[Alexx0612]

When I threw a mushroom in Sidestepper my game crashed.

Added in 1 hour 53 minutes 47 seconds:

[KBM-Quine]

When I threw a mushroom in Sidestepper my game crashed.

Added in 1 hour 53 minutes 47 seconds:

sorry for the late reply. to my knowledge there's nothing i can do about that aside from revert the code to a version where thrown npcs can kill other npcs. i'll log it as a known bug.

[KBM-Quine]

i can't replicate the sidestepper crash in b5, so i'm removing that from the op now. also i'll take this time to mention everything seems works fine as-is in b5. happy update everybody!

[AppleTheTomato]

Strange bug I found: the library has it's onPostReserveUse function setup like this:

Code: Select all

function modernReserveItems.onPostReserveUse(npc, p)
    -- empty
end

Super awesome that this is available, and helps a lot with a weird thing I'm doing, but when it's called at the end of .drop, it's setup like THIS:

Code: Select all

p.reservePowerup = 0
modernReserveItems.onPostReserveUse(p, MRINPC)
return MRINPC

This is a pretty easy fix I know, but I figured I should call it out before I do anything with these. Especially since I don't want to swap the variables around in one of these places and have the proper fix swap them in the other place, if that makes sense.

EDIT: After getting some help with custom events myself, and testing a couple things out, it looks like without using registerCustomEvent for modernReserveItems' custom events, you can only have one instance of those event across anything you use. Hopefully that could get fixed, too?

[KBM-Quine]

Strange bug I found: the library has it's onPostReserveUse function setup like this:

Code: Select all

function modernReserveItems.onPostReserveUse(npc, p)
    -- empty
end

Super awesome that this is available, and helps a lot with a weird thing I'm doing, but when it's called at the end of .drop, it's setup like THIS:

Code: Select all

p.reservePowerup = 0
modernReserveItems.onPostReserveUse(p, MRINPC)
return MRINPC

This is a pretty easy fix I know, but I figured I should call it out before I do anything with these. Especially since I don't want to swap the variables around in one of these places and have the proper fix swap them in the other place, if that makes sense.

i'm not sure what your pointing out here? i can't call something after return is called as that stops execution of that scope last i knew.

[AppleTheTomato]

Strange bug I found: the library has it's onPostReserveUse function setup like this:

Code: Select all

function modernReserveItems.onPostReserveUse(npc, p)
    -- empty
end

Super awesome that this is available, and helps a lot with a weird thing I'm doing, but when it's called at the end of .drop, it's setup like THIS:

Code: Select all

p.reservePowerup = 0
modernReserveItems.onPostReserveUse(p, MRINPC)
return MRINPC

This is a pretty easy fix I know, but I figured I should call it out before I do anything with these. Especially since I don't want to swap the variables around in one of these places and have the proper fix swap them in the other place, if that makes sense.

i'm not sure what your pointing out here? i can't call something after return is called as that stops execution of that scope last i knew.

Ah, I'm sorry. I was trying to point out that the "external wrappers" example of onPostReserveUse had (npc, p), while the call to the function near the bottom with return MRINPC had (p, MRINPC), swapping the variables around. Wasn't trying to say anything about the return part lol.

[KBM-Quine]

so uh. after forgetting to fix AppleTheTomato's problem for a bit, i kinda... throw out the whole patterns part of the library (basically half of it lol) and replaced it with a configs systems taken from the NPC.config system. i figure that warrants a new major version. this will not be compatible with older code relying on 1.3, you have been warned.
changelog:

-- v2.0 (4/14/2024) --

• rebuilt/took config system from npcconfig_core.lua. this reduces alot of repeat code.
• patterns have been completely removed as a result of the config system overhaul.
• resolveThrowSettings has been removed due to config overhaul as well.
• removed an unnecessary loop for warp checking.
• more code comments (for personal rememberance).
• any mem addresses that have field equivalents in B5 have been updated.
• isMega has been completely removed.
• isContained & containedID have been combined into one config, forcedState.
• allowContainedItems has been renamed allowForcedStateItems as following the config renamed
• isEgg has been replaced by idOverwrite. useful for container npcs.
• SFX has been renamed to sfx.
• the ai config table has been separated into indivdual ai# fields (1-6).
• onReserveUse has lost the throwSettings argument following config overhaul.
• fixed onPostReserveUse not returning the resulting npc from .drop
• onReserveUse and onPostReserveUse have been made to work across mulitle lua files (see included example materials for how)

the top post has been updated, see it for more details.