Item Roulette library for Lua (itemroulette getter/setter, item roulette functions)

Summary

This branch exposes the item roulette system to Lua. It changes the following:

• Implements itemlist_t as a member to itemroulette_t, acting as the type holding the item reel array, to better expose it as a metatable type to Lua.
• Allows itemroulette from player_t to be get (not set) as well as get/set its members (except itemlist which cannot be set, see below) through Lua.
• Refactored some code to create new methods (namely K_CreateAndShuffleItemReel).
• Exposes the following functions:
  • k_kart.h
    • K_GetShieldFromItem(kartitems_t item)
    • K_ItemResultToType(kartitems_t item)
    • K_ItemResultToAmount(kartitems_t item)
    • K_GetItemCooldown(kartitems_t item)
    • K_SetItemCooldown(kartitems_t item, tic_t time)
    • K_TimeAttackRules()
    • K_CapsuleTimeAttackRules()
  • k_boss.h
    • K_CheckBossIntro()
  • k_roulette.h
    • K_ItemEnabled(kartitems_t item)
    • K_ItemSingularity(kartitems_t item)
    • K_GetBotItemPriority(kartitems_t item)
    • K_AddItemToReel(player_t player/itemroulette_t roulette, [kartitems_t item/table items])
    • K_PushToRouletteItemList(player_t player/itemroulette_t roulette, [kartitems_t item/table items])
    • K_StartItemRoulette(player_t player, [boolean ringbox])
    • K_StartEggmanRoulette(player_t player)
    • K_StopRoulette(player_t player)
    • K_KartGetItemResult(player_t player, kartitems_t item)
    • K_GetItemRouletteDistance(player_t player, int numplayers)
    • K_FindUseodds(player_t player)
    • K_CreateAndShuffleItemReel(player_t player/itemroulette_t roulette, [boolean freeplay])
    • K_ForcedSPB(player_t player)
    • K_DenyShieldOdds(kartitems_t item)
    • K_GetRouletteOffset(player_t player, [fixed_t renderDelta], [fixed_t fudge])
    • K_GetSlotOffset(player_t player, [fixed_t renderDelta], [fixed_t fudge])
    • K_CalculateRouletteSpeed(player_t player)
    • K_ScaleItemDistance(int distance, int numplayers)
    • K_ItemOddsScale(int playercount)
  • k_grandprix.h
    • K_CanChangeRules()
• Creates the following Lua-only functions to interact with the roulette's item reel (as opposed to interacting with the table directly, providing encapsulation):
  • K_WipeItemsInReel(player_t player/itemroulette_t roulette)
  • K_SetItemInReelByIndex(player_t player/itemroulette_t roulette, size_t index, kartitems_t item)
  • K_AddItemToReelByIndex(player_t player/itemroulette_t roulette, size_t index, kartitems_t item, [boolean addrings])
  • K_RemoveItemFromReelByIndex(player_t player/itemroulette_t roulette, size_t index)
• Creates the following Lua hooks to interact with how the item roulette populates the reel with items:
  • PreFillItemRoulette, function(player_t player, itemroulette_t roulette, boolean ringbox): Allows Lua to interact with the item roulette reel before any special conditions, but after speed calculations. Return true to completely override it, return false to allow it to continue.
  • FillItemRoulette, function(player_t player, itemroulette_t roulette): Allows Lua to interact with the item roulette reel under normal circumstances (no special conditions met).
• Exposes kartslotmachine_t values: KSM_BAR, KSM_DOUBLEBAR, KSM_TRIPLEBAR, KSM_RING, KSM_SEVEN, KSM_JACKPOT, KSM__MAX.
• Exposes itemflags_t values: IF_USERINGS, IF_ITEMOUT, IF_EGGMANOUT, IF_HOLDREADY.
• Makes the item reel's contents dynamically allocated by default, allowing up to technically infinite items in the item reel.

Testing

The testing environment is ringracers_itemRouletteLib.exe -console -skipintro -warp RR_TESTRUN +addfile itemroulette.lua.

I used a script, itemroulette.lua, to test nearly all additions. Namely:

• Prints all exposed KSM_ and IF_ values in the console.
• Has a HUD hook that displays the values of all of the itemroulette_t values, including items in the item reel if active, the values from K_ScaleItemDistance, K_ItemOddsScale, K_GetRouletteOffset and K_GetSlotOffset.
• Has a command, setroulettevalue, that allows the itemroulette_t setter to be tested and its members changed to any value.
• Has console variables, enableprefillitemroulette, prefillroulettetype, and enablefillitemroulette, that allows you to play with the hook's roulette outcomes and test various functions.
  • If prefillroulettetype is set from 1 to 4 (and enableprefillitemroulette is On), Ring Boxes will give you an item reel with a guaranteed Jackpot.
  • If prefillroulettetype is set to 1, Item Boxes will use the same functions used from the regular roulette code with no special outcomes to recreate that type of roulette.
  • If prefillroulettetype is set to 2, Item Boxes will provide you with this item reel: KITEM_SNEAKER, KITEM_ORBINAUT, KITEM_SPB, KITEM_GACHABOM, KRITEM_TRIPLESNEAKER. This tests adding items to the roulette using both the table and integer parameter types using K_AddItemToReel.
  • If prefillroulettetype is set to 3, ditto, but uses K_PushToRouletteItemList instead.
  • If prefillroulettetype is set to 4, the roulette is similar to 3, but will use K_ItemEnabled to check if the item should be in the reel. For the SPB, it will check if it is not under any cooldown using K_GetItemCooldown. Afterwards, it will give the SPB a 4 second cooldown using K_SetItemCooldown. It will also print some values related to K_ItemSingularity, K_GetBotItemPriority, and K_GetShieldFromItem.
  • If enableprefillitemroulette is Off, and enablefillitemroulette is On, then it will use the functions K_WipeItemsInReel, K_PushToRouletteItemList, K_SetItemInReelByIndex, K_AddItemToReelToIndex and K_RemoveItemFromReelToIndex to test those functions, specifically bounds checking.
  • If prefillroulettetype is set to 5, 1500 items will be added to the roulette (30 items * 50 iterations) to test dynamic allocation.
• userouletteasparam toggles if the getter/setter debug HUD should be enabled, default On.
• userouletteasparam toggles if it uses the hooks' itemroulette_t object instead of the player_t object for all applicable function calls, default Off.
• Various other commands exist to test miscellaneous functions:
  • myitems: If a roulette is ongoing, it will print on the console the items that reside on the item reel using the itemlist_t getters.
  • startroulette: Starts an item roulette using K_StartItemRoulette. startroulette true will start a Slot Reel instead of an Item Reel.
  • starteggman: Starts an item roulette rigged by an Eggman Monitor using K_StartEggmanRoulette.
  • stoproulette: Stops an item roulette if one is ongoing using K_StopRoulette.
  • timeattacktest: Prints in console the results of the K_TimeAttackRules and K_CapsuleTimeAttackRules functions.
  • testitemhelpers: Requires an item roulette index argument - it will use the methods K_ItemResultToAmount and K_ItemResultToType` to print what the player would be getting out of the item roulette reel result.
  • undefinedbehaviourtest: Tests an underfined behaviour bug on itemlist local variables not preserving between map changes.
  • kartgetitemresult: Uses K_KartGetItemResult to give the player the item result from the arguemnt passed (a kartitems_t index).
  • calcroulettespeed: If the roulette is ongoing, K_CalculateRouletteSpeed is used to recalculate the roulette speed.
  • bossintro: Prints if a boss intro is ongoing using K_CheckBossIntro.
  • canchangerules: Prints if the rules can be changed (specific to Grand Prix) using K_CanChangeRules.

Changelog

• Exposed almost all of the item roulette system to Lua, as well as functions and methods related to it.