Skip to main content

ProgressionUtils

A collection of utilities for progression-related development.

Properties​

Quests​

</>
ProgressionUtils.Quests: Quests

Utilities for managing quest data and progress.

Quests.MakeQuest : (QuestData : QuestData) -> Quest

Creates a quest instance that can be started and progressed by players.

Quest

Created by Quests.MakeQuest.

type Quest = QuestData & {
    OnStepIncrement : Types.Signal<Player, number>, -- A signal that fires when a step of a quest is incremented
    OnStart : Types.Signal<Player>, -- A signal that fires when a quest is started
    OnComplete : Types.Signal<Player>, -- A signal that fires when a quest is completed
    OnStepComplete : Types.Signal<Player>, -- A signal that fires when a quest step is completed

    Start : (Player : Player, ExistingProgress : QuestProgress) -> QuestProgress, -- A function that takes a player and their existing progress, and begins the quest. Returns the updated quest progress table.
    MakeProgress : (Player : Player, ExistingProgress : QuestProgress, StepProgressed : number, AmountProgressed : number) -> QuestProgress, -- A function that takes a player and their existing progress, as well as the step progress and the amount progressed, and makes progress on that quest step. If the quest is complete, it will be marked as complete. Returns current the quest progress
}

To start a quest, call Quest.Start(), like so:

local NewProgress = ExampleQuest.Start(Player, ExistingProgress)

Then, when progressing a quest, call Quest.MakeProgress(), like so:

local NewProgress = ExampleQuest.MakeProgress(Player, ExistingProgress, 1, 1)

Quests.GetBlankProgressTable : () -> QuestProgress

Returns a dictionary of blank quest progress of QuestProgress type.

Quests.SerializeProgressTable : (Progress : QuestProgress) -> string

Equivalent to HttpService:JSONEncode(); serializes a progress table to a string.

Quests.DeserializeProgressTable : (ProgressSerialized : string) -> QuestProgress

Equivalent to HttpService:JSONDecode(); deserializes a string to a table of QuestProgress type.

Quests.HasCompletedQuest : (ExistingProgress : QuestProgress, QuestId : string)

Checks if a quest is completed, given the existing progress and quest id.

type QuestData

QuestData is a dictionary of the following type:

type QuestData = {
    QuestId : string, -- An indentifier string for the quest, must be unique
    QuestName : string?, -- The frontend name for the quest
    QuestDescription : string?, -- A frontend description of the quest
    QuestReward : (Player : Player) -> nil, -- The quest reward, which is a function that takes the player completing the quest
    RequireStepsInOrder : boolean, -- If true, QuestSteps must be done in order

    QuestSteps : {[number] : { -- Array of quest steps
        MaxProgressionAmount : number, -- For this step, what the maximum count of an action is
        StepName : string?, -- The frontend name for the step
        StepDescription : string?, -- The frontend description for the step
    }}
}

type QuestProgress

QuestProgress is a dictionary of the following type:

type QuestProgress = {
CompletedQuestIds : {string}, -- Quest ids representing completed quests

QuestsInProgress : { -- Quest data for in-progress quests
        {
            QuestId : string, -- Id of in-progress quest
            StepProgress : {[number] : number}, -- Progress of quest steps
            StepsCompleted : number, -- Number of steps completed
            PercentCompleted : number, -- Percent of steps completed
        }
    }
}

Scores​

</>
ProgressionUtils.Scores: Scores

Utilities for managing scores, which is helpful for things like XP or currency.

WARNING

Make sure to guarantee that you call DeclareSetScoreCallback and DeclareGetScoreCallback before SetScore and GetScore. Not doing so will lead to a race condition.

Scores.DeclareSetScoreCallback : (Callback : (Player, string, number))

Sets Scores.SetScore to a callback used by the rest of the module.

Scores.DeclareGetScoreCallback : (Callback : (Player, string))

Sets Scores.GetScore to a callback used by the rest of the module.

Scores.SetScore : (Player : Player, ScoreType : string, ScoreValue : number)

Sets the score for a player, given a score type and value. This function doesn't exist until Scores.DeclareSetScoreCallback() is called!

Scores.GetScore : (Player : Player, ScoreType : string)

Gets the score for a player, given a score type. This function doesn't exist until Scores.DeclareGetScoreCallback() is called!

Scores.AddScoreForPlayer : (Player : Player, ScoreType : string, AddedAmount : number)

Adds score to a player, given the type and added amount. This can be multiplied by boosters.

Scores.AddScoreForPlayerRaw : (Player : Player, ScoreType : string, AddedAmount : number)

Adds score to a player, given the type and added amount. This can not be multiplied by boosters.

Scores.RemoveScoreForPlayer : (Player : Player, ScoreType : string, RemovedAmount : number)

Removes score from a player, given the type and removed amount. This is never affected by boosters.

Scores.HasAtLeast : (Player : Player, ScoreType : number, Minimum : number) -> boolean

Returns true if the player has an amount of score of certain type.

Boosters​

</>
ProgressionUtils.Boosters: Boosters

Utilities for applying boosters, which affects scores.

Boosters.ApplyBooster : (Player : Player, BoosterData : BoosterDataInput)

Applies a booster to a player, given the inputted booster data as a table. Automatically cleans up after the time is complete, and does not carry between servers.

Boosters.BoosterApplied : Signal<Player, BoosterData>

A signal that fires when a booster is applied to a player.

Boosters.BoosterEnded : Signal<Player, BoosterData>

A signal that fires when a booster is removed from a player.

Boosters.GetActiveBoosters : (Player : Player) -> {BoosterData}

Gets all active boosters for player.

Boosters.GetTimeLeftForBooster : (Player : Player, BoosterId : string) -> number

Gets time left for newest booster of given id for a player. If no booster is in progress for the player, this returns 0.

Boosters.IsBoosterActive : (Player : Player, BoosterId : string) -> boolean

Returns true if the player is using at least one booster of the given id.

Boosters.GetScoreMultiplier : (Player : Player, ScoreId : string) -> number

Gets a multiplier applied to a score given the boosters from a player. If no boosters are affecting that score, this returns 1.

type BoosterDataInput

BoosterDataInput is the following type:

type BoosterDataInput = {
    BoosterId : string, -- The unique identifier for the booster
    ScoreId : string, -- The id of the score affected by the booster
    BoostMultiplier : number, -- The multiplier applied to the score (e.g. 1.5 to give +50% boost)
    StackMethod : "AddTime" | "Separate", -- Declares how the booster stacks with the same type. AddTime adds time, Separate adds a separate boost which stacks multiplier
    TotalTime : number, -- How long the boost lasts, in seconds
}

type BoosterData

BoosterData is the following type:

type BoosterData = BoosterDataInput & {
    StartingTime : number,
    Bucket : any,
}

Inventory​

</>
ProgressionUtils.Inventory: Inventory

Utilities for basic inventory management.

Inventory.AddItemInventory : (InventoryData : InventoryData, ItemData : ItemDataInput, MaxStack : number) -> InventoryData

Adds/stacks an item in an inventory given existing inventory data, the item data, and max stack. If a stack of an item goes above MaxStack, it will automatically create a new stack. Returns the new inventory data.

Inventory.RemoveItemFromInventory : (InventoryData : InventoryData, ItemId : string) -> InventoryData

Removes an item in an inventory given existing inventory data and item id. If the item has more than one in a stack, it just reduces the quantity in the stack by 1. Returns the new inventory data.

Inventory.DoesOwnItem : (InventoryData : InventoryData, ItemId : string) -> boolean

Returns true if an item of given id is in the inventory data.

Inventory.GetBlankInventoryData : () -> InventoryData

Returns a blank inventory formatted to InventoryData type.

Inventory.SerializeInventory : (InventoryData : InventoryData) : string

Equivalent to HttpService:JSONEncode(); turns inventory data into a string.

Inventory.DeserializeInventory : (SerializedData : string) : InventoryData

Equivalent to HttpService:JSONDecode(); turns serialized inventory data into an inventory data table.

type ItemDataInput

This is the type for ItemDataInput:

type ItemDataInput = {
    ItemId : string, -- The unique id of the item 
    [string] : any, -- Any other properties you want to add, all optional and not used by the system
}

type ItemData

This is the type for ItemData:

type ItemData = ItemDataInput & {
    Quantity : number,
}

type InventoryData

This is the type for InventoryData:

type InventoryData = {
    Items : {ItemData}
}
Show raw api
{
    "functions": [],
    "properties": [
        {
            "name": "Quests",
            "desc": "Utilities for managing quest data and progress.\n\n### `Quests.MakeQuest : (QuestData : QuestData) -> Quest`\nCreates a quest instance that can be started and progressed by players.\n\n### `Quest`\nCreated by `Quests.MakeQuest`.\n\n```lua\ntype Quest = QuestData & {\n    OnStepIncrement : Types.Signal<Player, number>, -- A signal that fires when a step of a quest is incremented\n    OnStart : Types.Signal<Player>, -- A signal that fires when a quest is started\n    OnComplete : Types.Signal<Player>, -- A signal that fires when a quest is completed\n    OnStepComplete : Types.Signal<Player>, -- A signal that fires when a quest step is completed\n\n    Start : (Player : Player, ExistingProgress : QuestProgress) -> QuestProgress, -- A function that takes a player and their existing progress, and begins the quest. Returns the updated quest progress table.\n    MakeProgress : (Player : Player, ExistingProgress : QuestProgress, StepProgressed : number, AmountProgressed : number) -> QuestProgress, -- A function that takes a player and their existing progress, as well as the step progress and the amount progressed, and makes progress on that quest step. If the quest is complete, it will be marked as complete. Returns current the quest progress\n}\n```\n\nTo start a quest, call `Quest.Start()`, like so:\n\n```lua\nlocal NewProgress = ExampleQuest.Start(Player, ExistingProgress)\n```\n\nThen, when progressing a quest, call `Quest.MakeProgress()`, like so:\n\n```lua\nlocal NewProgress = ExampleQuest.MakeProgress(Player, ExistingProgress, 1, 1)\n```\n\n### `Quests.GetBlankProgressTable : () -> QuestProgress`\nReturns a dictionary of blank quest progress of `QuestProgress` type.\n\n### `Quests.SerializeProgressTable : (Progress : QuestProgress) -> string`\nEquivalent to `HttpService:JSONEncode()`; serializes a progress table to a string.\n\n### `Quests.DeserializeProgressTable : (ProgressSerialized : string) -> QuestProgress`\nEquivalent to `HttpService:JSONDecode()`; deserializes a string to a table of `QuestProgress` type.\n\n### `Quests.HasCompletedQuest : (ExistingProgress : QuestProgress, QuestId : string)`\nChecks if a quest is completed, given the existing progress and quest id.\n\n### `type QuestData`\nQuestData is a dictionary of the following type:\n\n```lua\ntype QuestData = {\n    QuestId : string, -- An indentifier string for the quest, must be unique\n    QuestName : string?, -- The frontend name for the quest\n    QuestDescription : string?, -- A frontend description of the quest\n    QuestReward : (Player : Player) -> nil, -- The quest reward, which is a function that takes the player completing the quest\n    RequireStepsInOrder : boolean, -- If true, QuestSteps must be done in order\n\n    QuestSteps : {[number] : { -- Array of quest steps\n        MaxProgressionAmount : number, -- For this step, what the maximum count of an action is\n        StepName : string?, -- The frontend name for the step\n        StepDescription : string?, -- The frontend description for the step\n    }}\n}\n```\n\n### `type QuestProgress`\nQuestProgress is a dictionary of the following type:\n\n```lua\ntype QuestProgress = {\nCompletedQuestIds : {string}, -- Quest ids representing completed quests\n\nQuestsInProgress : { -- Quest data for in-progress quests\n        {\n            QuestId : string, -- Id of in-progress quest\n            StepProgress : {[number] : number}, -- Progress of quest steps\n            StepsCompleted : number, -- Number of steps completed\n            PercentCompleted : number, -- Percent of steps completed\n        }\n    }\n}\n```",
            "lua_type": "Quests",
            "source": {
                "line": 100,
                "path": "src/Packages/_Index/miagobble_progression-utils@1.0.1/progression-utils/init.luau"
            }
        },
        {
            "name": "Scores",
            "desc": "Utilities for managing scores, which is helpful for things like XP or currency.\n\n:::warning\n\nMake sure to guarantee that you call `DeclareSetScoreCallback` and `DeclareGetScoreCallback` before `SetScore` and `GetScore`.\nNot doing so will lead to a race condition.\n\n:::\n\n### `Scores.DeclareSetScoreCallback : (Callback : (Player, string, number))`\nSets `Scores.SetScore` to a callback used by the rest of the module.\n\n### `Scores.DeclareGetScoreCallback : (Callback : (Player, string))`\nSets `Scores.GetScore` to a callback used by the rest of the module.\n\n### `Scores.SetScore : (Player : Player, ScoreType : string, ScoreValue : number)`\nSets the score for a player, given a score type and value. **This function doesn't exist until `Scores.DeclareSetScoreCallback()` is called!**\n\n### `Scores.GetScore : (Player : Player, ScoreType : string)`\nGets the score for a player, given a score type. **This function doesn't exist until `Scores.DeclareGetScoreCallback()` is called!**\n\n### `Scores.AddScoreForPlayer : (Player : Player, ScoreType : string, AddedAmount : number)`\nAdds score to a player, given the type and added amount. This can be multiplied by boosters.\n\n### `Scores.AddScoreForPlayerRaw : (Player : Player, ScoreType : string, AddedAmount : number)`\nAdds score to a player, given the type and added amount. This can **not** be multiplied by boosters.\n\n### `Scores.RemoveScoreForPlayer : (Player : Player, ScoreType : string, RemovedAmount : number)`\nRemoves score from a player, given the type and removed amount. This is never affected by boosters.\n\n### `Scores.HasAtLeast : (Player : Player, ScoreType : number, Minimum : number) -> boolean`\nReturns `true` if the player has an amount of score of certain type.",
            "lua_type": "Scores",
            "source": {
                "line": 140,
                "path": "src/Packages/_Index/miagobble_progression-utils@1.0.1/progression-utils/init.luau"
            }
        },
        {
            "name": "Boosters",
            "desc": "Utilities for applying boosters, which affects scores.\n\n### `Boosters.ApplyBooster : (Player : Player, BoosterData : BoosterDataInput)`\nApplies a booster to a player, given the inputted booster data as a table. Automatically cleans up after the time is complete, and does not carry between servers.\n\n### `Boosters.BoosterApplied : Signal<Player, BoosterData>`\nA signal that fires when a booster is applied to a player.\n\n### `Boosters.BoosterEnded : Signal<Player, BoosterData>`\nA signal that fires when a booster is removed from a player.\n\n### `Boosters.GetActiveBoosters : (Player : Player) -> {BoosterData}`\nGets all active boosters for player.\n\n### `Boosters.GetTimeLeftForBooster : (Player : Player, BoosterId : string) -> number`\nGets time left for newest booster of given id for a player. If no booster is in progress for the player, this returns `0`.\n\n### `Boosters.IsBoosterActive : (Player : Player, BoosterId : string) -> boolean`\nReturns `true` if the player is using at least one booster of the given id.\n\n### `Boosters.GetScoreMultiplier : (Player : Player, ScoreId : string) -> number`\nGets a multiplier applied to a score given the boosters from a player. If no boosters are affecting that score, this returns `1`.\n\n### `type BoosterDataInput`\nBoosterDataInput is the following type:\n\n```lua\ntype BoosterDataInput = {\n    BoosterId : string, -- The unique identifier for the booster\n    ScoreId : string, -- The id of the score affected by the booster\n    BoostMultiplier : number, -- The multiplier applied to the score (e.g. 1.5 to give +50% boost)\n    StackMethod : \"AddTime\" | \"Separate\", -- Declares how the booster stacks with the same type. AddTime adds time, Separate adds a separate boost which stacks multiplier\n    TotalTime : number, -- How long the boost lasts, in seconds\n}\n```\n\n### `type BoosterData`\nBoosterData is the following type:\n\n```lua\ntype BoosterData = BoosterDataInput & {\n    StartingTime : number,\n    Bucket : any,\n}\n```",
            "lua_type": "Boosters",
            "source": {
                "line": 193,
                "path": "src/Packages/_Index/miagobble_progression-utils@1.0.1/progression-utils/init.luau"
            }
        },
        {
            "name": "Inventory",
            "desc": "Utilities for basic inventory management.\n\n### `Inventory.AddItemInventory : (InventoryData : InventoryData, ItemData : ItemDataInput, MaxStack : number) -> InventoryData`\nAdds/stacks an item in an inventory given existing inventory data, the item data, and max stack. If a stack of an item goes above `MaxStack`, it will automatically create a new stack.\nReturns the new inventory data.\n\n### `Inventory.RemoveItemFromInventory : (InventoryData : InventoryData, ItemId : string) -> InventoryData`\nRemoves an item in an inventory given existing inventory data and item id. If the item has more than one in a stack, it just reduces the quantity in the stack by 1.\nReturns the new inventory data.\n\n### `Inventory.DoesOwnItem : (InventoryData : InventoryData, ItemId : string) -> boolean`\nReturns `true` if an item of given id is in the inventory data.\n\n### `Inventory.GetBlankInventoryData : () -> InventoryData`\nReturns a blank inventory formatted to `InventoryData` type.\n\n### `Inventory.SerializeInventory : (InventoryData : InventoryData) : string`\nEquivalent to `HttpService:JSONEncode()`; turns inventory data into a string.\n\n### `Inventory.DeserializeInventory : (SerializedData : string) : InventoryData`\nEquivalent to `HttpService:JSONDecode()`; turns serialized inventory data into an inventory data table.\n\n### `type ItemDataInput`\nThis is the type for ItemDataInput:\n\n```lua\ntype ItemDataInput = {\n    ItemId : string, -- The unique id of the item \n    [string] : any, -- Any other properties you want to add, all optional and not used by the system\n}\n```\n\n### `type ItemData`\nThis is the type for ItemData:\n\n```lua\ntype ItemData = ItemDataInput & {\n    Quantity : number,\n}\n```\n\n### `type InventoryData`\nThis is the type for InventoryData:\n\n```lua\ntype InventoryData = {\n    Items : {ItemData}\n}\n```",
            "lua_type": "Inventory",
            "source": {
                "line": 250,
                "path": "src/Packages/_Index/miagobble_progression-utils@1.0.1/progression-utils/init.luau"
            }
        }
    ],
    "types": [],
    "name": "ProgressionUtils",
    "desc": "A collection of utilities for progression-related development.",
    "source": {
        "line": 6,
        "path": "src/Packages/_Index/miagobble_progression-utils@1.0.1/progression-utils/init.luau"
    }
}