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

JugadorXEIrequested to merge
JugadorXEI/RingRacers:itemRouletteLib into master

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.
Edited by JugadorXEI

Merge request reports