Merge pull request #101 from Gc-network/feature/documentation

Facts update

documentation/docs/docs/05-facts.mdx

@@ -0,0 +1,117 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Facts
+
+Facts are essentially variables. They store information that can be modified by other entries. All facts are numbers and are treated as such.
+
+:::info
+Facts are stored per player, not for the server or world, unless otherwise specified.
+:::
+
+The [`Basic Adapter`](../adapters/BasicAdapter) encompasses numerous facts available for use. However, it's important to note that [`adapters`](adapters) have the capability to further augment the array of available facts.
+
+## Why Use Facts?
+
+Facts play a crucial role in dynamic content creation and system behavior customization. Here are some reasons to consider using facts:
+
+- **Dynamic Quests:** Track player progress in quests by using facts to store and modify completion status.
+
+- **Customization:** Personalize player experiences by utilizing facts to adjust in-game parameters, such as difficulty levels or character attributes.
+
+- **Interactive Storytelling:** Enhance narrative elements by employing facts to remember player choices and actions, shaping the evolving story.
+
+- **Achievement Systems:** Implement achievement tracking by using facts to record specific milestones and accomplishments.
+
+### Types of facts
+Facts have two types: Readable and Writable.
+- **Readable Facts:** Used in the criteria of an entry. For example, checking if a player has a certain item in their inventory.
+- **Writable Facts:** Used in modifiers to modify the fact's value. For instance, updating a player's quest progression.
+
+:::info
+Some facts are both readable and writable. For example, the [Permanent Fact](../adapters/BasicAdapter/entries/fact/permanent_fact) can be used in both criteria and modifiers.
+But some facts are only readable. For example, the [Inventory Item Count Fact](../adapters/BasicAdapter/entries/fact/inventory_item_count_fact) can only be used in criteria.
+:::
+## Fields
+In some entries, there are fields that influence the way facts are handled.
+
+![Criterion Fields](./assets/facts/criteria_and_modifier.png)
+
+### Criteria
+
+Criteria is the condition for an entry, e.g., `if fact = 10 then...`. It controls whether an entry will occur.
+
+![Criterion Fields](./assets/facts/criteria.png)
+
+When using Criteria, follow these steps:
+1. Select the fact to check.
+2. Choose the operator.
+3. Insert the value for the operator to check.
+
+### Modifiers
+
+Modifiers, as the name suggests, modify a fact.
+
+![Modifier Fields](./assets/facts/modifier.png)
+
+When using Modifiers, follow these steps:
+1. Select the fact to modify.
+2. Choose the operator. You can change the value directly (=) or add to it (+).
+3. Insert the value for the operator to modify.
+
+:::warning
+Modifiers only run when the entry is executed.
+If the entry has criteria and **one of the criteria** is `false`, then the entry won't be executed, and the fact won't be modified.
+:::
+
+## Tutorial
+To get you started with facts, we will use a permanent fact to track progression in a quest.
+
+1. Create a new page and select it as `static`. Give it the name `Playerprogress`
+2. Click on the + icon and select `Add Permanent Fact`. Rename it to `Playerprogress` and give it a nice comment.
+![Static Page Button](./assets/facts/static-page.png)
+3. On the sequence page, click on an action.
+   - Set a **Criteria:** Check if `Playerprogress` == 0.
+   - Set a **Modifier:** If criteria are met, update `Playerprogress` to 1.
+4. Create additional actions to represent different quest stages, modifying `Playerprogress` accordingly.
+
+## Examples
+There are many possibilities with the facts system. Here are some examples:
+<Tabs>
+   <TabItem value="Gathering Items Quest" label="Gathering Items Quest" default>
+      **Objective:** A player talks to an NPC and needs to gather items.
+
+      **Fact Used:**
+      - **Readable Fact:** [Inventory Item Count](../adapters/BasicAdapter/entries/fact/inventory_item_count_fact)
+
+      **Scenario:**
+      1. Player talks to the NPC.
+      2. Criteria check using the Inventory Item Count Fact to verify if the player has the required items.
+   </TabItem>
+   <TabItem value="Progression Tracking" label="Progression Tracking">
+      **Objective:** Track a player's progression through different quest stages.
+
+      **Fact Used:**
+      - **Writable Fact:** [Permanent Fact](../adapters/BasicAdapter/entries/fact/permanent_fact)
+
+      **Scenario:**
+      1. Player talks to an NPC (Progression set to 1).
+      2. Completes a specific action (Progression set to 2).
+      3. Finishes the quest (Progression set to 3).
+   </TabItem>
+   <TabItem value="Balance check" label="Balance check">
+      **Objective:** See if a player has enough money to buy an item.
+
+      **Fact Used:**
+      - **Readable Fact:** [balance fact](../adapters/VaultAdapter/entries/fact/balance_fact)
+
+      **Scenario:**
+      1. Player talks to an NPC.
+      2. Criteria check using the balance fact to see if the player has enough balance.
+      3. If the player has enough balance, they can buy the item.
+      4. If the player doesn't have enough balance, show a message to the player.
+   </TabItem>
+</Tabs>
+:::tip
+To see all the available facts, check out the [Adapters section](../adapters).
+:::