diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index b41242e0..2f3aca51 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -66,6 +66,7 @@ module.exports = { { text: "Coercable Components", link: "/guide/important-concepts/coercable" }, { text: "Reactivity", link: "/guide/important-concepts/reactivity" }, { text: "Persistence", link: "/guide/important-concepts/persistence" }, + { text: "Requirements", link: "/guide/important-concepts/requirements" }, { text: "Formulas", link: "/guide/important-concepts/formulas" } ] }, diff --git a/docs/guide/important-concepts/requirements.md b/docs/guide/important-concepts/requirements.md new file mode 100644 index 00000000..57cade10 --- /dev/null +++ b/docs/guide/important-concepts/requirements.md @@ -0,0 +1,21 @@ +# Requirements + +The requirements system in Profectus is designed to handle various conditions that must be met before certain actions or features can be accessed by the player. These conditions can include resource amounts, completed challenges, or other milestones within the game. + +## Creating Requirements + +To create a requirement, you can use one of the provided utility functions like [createCostRequirement](/api/modules/game/requirements#createcostrequirement), [createVisibilityRequirement](/api/modules/game/requirements#createvisibilityrequirement), or [createBooleanRequirement](/api/modules/game/requirements#createbooleanrequirement). These functions return a `Requirement` object with specific properties that define the requirement conditions. + +## Using Requirements + +Several features will have a `requirements` property that takes one or more requirements that must be fulfilled for a certain action to be performed with that feature. + +When implementing requirements, you can use the [displayRequirements](/api/modules/game/requirements#displayrequirements) utility. This utility is designed to give a human-readable string generated by the requirement(s) given, making it easier for players to understand the conditions needed to progress in the game. Typically features that support requirements will already use this utility internally. + +You may need to "pay" requirements upon meeting their conditions and performing the associated action. This action typically involves spending resources or making other adjustments to the game state. The [payRequirements](/api/modules/game/requirements#payrequirements) function simplifies this process by handling the payment for one or more requirements, considering the number of levels to pay for. Additionally, custom pay functions like [payByDivision](/api/modules/game/requirements#paybydivision) and [payByReset](/api/modules/game/requirements#paybyreset) can be passed into `createCostRequirement` for more specialized cases. + +## Multi-Level Requirements + +Requirements can have multiple "levels", which are typically used for things like multi-level challenges with scaling requirements. When checking if requirements are met, the [requirementsMet](/api/modules/game/requirements#requirementsmet) function can be used. It accepts a single requirement or an array of requirements. + +Requirements that are just on/off, such as boolean or visibility requirements, will count as infinite levels when in the same array. This allows you to combine different types of requirements in the same array and use the [maxRequirementsMet](/api/modules/game/requirements#maxrequirementsmet) function to calculate the maximum number of levels that could be acquired with the current requirement states.