Create Entity Objectives

documentation/docs/docs/03-creating-stories/05-questing/02-entity-objectives.mdx

@@ -0,0 +1,191 @@
+import Player from "@site/src/components/Player";
+import EntryDisplay from "@site/src/components/EntryDisplay";
+import EntrySearch from "@site/src/components/EntrySearch";
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import Figure from "@site/src/components/Figure";
+
+# Entity Objectives
+
+:::info[Before starting]
+We recommend reading the [Questing](./index.mdx) guide before starting this tutorial, as it provides essential background knowledge for understanding [Interact Entity Objectives](../../../adapters/EntityAdapter/entries/quest/interact_entity_objective.mdx).
+:::
+
+In this tutorial, you'll learn how to create and implement [Interact Entity Objectives](../../../adapters/EntityAdapter/entries/quest/interact_entity_objective.mdx), a powerful feature that enhances player guidance to Non-Player Characters (NPCs) in your Minecraft Server.
+
+## Understanding [Interact Entity Objectives](../../../adapters/EntityAdapter/entries/quest/interact_entity_objective.mdx)
+
+[Interact Entity Objectives](../../../adapters/EntityAdapter/entries/quest/interact_entity_objective.mdx) are a specific quest objective that involve player interaction with NPCs.
+These objectives add depth to Typewriters questing system by creating meaningful encounters and dialogues with characters in your world.
+They can range from simple conversations to complex multi-stage interactions that drive your game's narrative forward.
+
+Key benefits of using [Interact Entity Objectives](../../../adapters/EntityAdapter/entries/quest/interact_entity_objective.mdx) include:
+- Creating more immersive and interactive quest lines
+- Guiding players through the game world in a natural, story-driven manner
+- Providing visual cues to help players identify important NPCs
+
+## Story Overview
+
+Let's create a quest called _**"A Sip of Memories"**_ that showcases the use of entity objectives. This quest will guide the player through interactions with different NPCs to complete a heartwarming task.
+
+<Tabs>
+  <TabItem value="stage1" label="Introduction" default>
+
+    **Location**: Town square, near a large oak tree
+
+    **Character**: Elias Thornberry (elderly man)
+
+    **Player Actions**: 
+    - Approach and speak to Elias
+    - Listen to his reminiscence about the tree and his late wife, Rosemary
+    - Receive the request to fetch water
+
+    **Outcome**: Quest initiated, player directed fetch water from Mira
+
+    **Note**: Players can interact with Mira before meeting Elias, establishing her character and the kiosk's presence in the game world.
+
+  </TabItem>
+  <TabItem value="stage2" label="Seeking Water">
+
+    **Location**: Mira's kiosk in the town
+
+    **Character**: Mira Swiftwater (kiosk owner)
+
+    **Player Actions**:
+    - Approach Mira's kiosk
+    - Request water for Elias
+    - Learn the price (20 emeralds)
+
+    **Possible Outcomes**:
+    1. If player has 20 emeralds:
+       - Purchase water
+       - Proceed to Stage 4
+    2. If player lacks 20 emeralds:
+       - Cannot purchase water
+       - Proceed to Stage 3
+
+    **Note**: If players return to Elias without water, he responds kindly, maintaining the option to complete the quest later.
+
+  </TabItem>
+  <TabItem value="stage3" label="Gathering Emeralds">
+
+    **Location**: Various locations in the game world
+
+    **Player Actions**:
+    - Explore and complete other tasks to earn emeralds
+    - Return to Mira's kiosk once 20 emeralds are collected
+
+    **Outcome**: Player can purchase water and proceed to Stage 4
+
+    **Note**: If players return to Elias without water, he responds kindly, maintaining the option to complete the quest later.
+
+   </TabItem>
+   <TabItem value="stage4" label="Quest Completion">
+
+    **Location**: Back at the oak tree in the town square
+
+    **Character**: Elias Thornberry
+
+    **Player Actions**:
+    - Return to Elias
+    - Give him the water
+
+    **Outcome**: 
+    - Elias expresses gratitude
+    - Shares another memory
+    - Gives player a small reward
+    - Quest completed
+
+  </TabItem>
+  <TabItem value="post-quest" label="Post-Quest">
+
+    **Location**: Oak tree in the town square
+
+    **Character**: Elias Thornberry
+
+    **Player Actions**: 
+    - Return to Elias at any time
+    - Listen to one of his random monologues about memories, the tree, or life observations
+
+    **Outcome**: Adds depth to the game world and Elias's character
+  </TabItem>
+</Tabs>
+
+## Configuring the Quest
+
+### Setup Pages
+To bring our quest to life, we need to configure several pages that define the NPCs, their dialogues, and the quest structure.
+These pages work together to create a cohesive quest experience:
+
+<EntryDisplay pages={[
+    require("./assets/entity_objectives/ent_obj_manifest.json"),
+    require("./assets/entity_objectives/ent_obj_sequence.json"),
+    require("./assets/entity_objectives/ent_obj_static.json"),
+]} />
+
+## Interact Entity Objective
+
+[Interact Entity Objectives](../../../adapters/EntityAdapter/entries/quest/interact_entity_objective.mdx) are a powerful tool that allows you to create objectives that require players to interact with specific NPCs.
+Here's how to set it up:
+
+<EntrySearch entryName="interact_entity_objective"/>
+
+In our _**"A Sip of Memories"**_ quest, we use multiple Interact Entity Objectives for different NPCs at various stages.
+For example, we have separate objectives for talking to Elias at the beginning of the quest and when the player returns with the water.
+
+### Visual Indicators
+
+The [Interact Entity Objective](../../../adapters/EntityAdapter/entries/quest/interact_entity_objective.mdx) comes with built-in visual cues to guide players:
+
+- When an objective is active for an NPC, an indicator appears above their head.
+- The indicator changes based on whether the player has the quest tracked or not.
+
+<div className="flex flex-col items-center justify-center space-y-4 md:space-y-0 md:flex-row md:space-x-4">
+    <Figure title="NPC Indicator when Quest is Tracked" img={require("./assets/entity_objectives/npc_indicator_tracked.png")} alt="NPC Indicator Tracked" width={400} />
+    <Figure title="NPC Indicator when Quest is Not Tracked" img={require("./assets/entity_objectives/npc_indicator_untracked.png")} alt="NPC Indicator Not Tracked" width={400} />
+</div>
+
+You can customize these indicators using [Snippets](../../05-helpfull-features/05-snippets.mdx) to match your game's aesthetic.
+
+## Interact Entity Objectives Path Stream
+
+To further assist players in navigating your game world, you can implement the [Interact Entity Objectives Path Stream](../../../adapters/EntityAdapter/entries/quest/interact_entity_objectives_path_stream.mdx). 
+This feature creates a visual path, guiding players to NPCs with active [Interact Entity Objectives](../../../adapters/EntityAdapter/entries/quest/interact_entity_objective.mdx) to those NPCs.
+
+<EntrySearch entryName="interact_entity_objectives_path_stream"/>
+
+Key features of the Path Stream:
+- Automatically generates paths to all NPCs with active [Interact Entity Objectives](../../../adapters/EntityAdapter/entries/quest/interact_entity_objective.mdx).
+- Only shows paths for objectives in currently tracked quests.
+- Helps players navigate complex game environments more easily.
+
+Here's a visual demonstration of the Path Stream in action:
+
+<Player url={require("./assets/entity_objectives/path_stream.webm").default} />
+
+## Quest Setup
+
+To bring all these elements together and create our _**"A Sip of Memories"**_ quest, we use the following quest configuration:
+
+<EntryDisplay pages={[
+    require("./assets/entity_objectives/ent_obj_quest.json"),
+]} referencePages={[
+    require("./assets/entity_objectives/ent_obj_manifest.json"),
+    require("./assets/entity_objectives/ent_obj_sequence.json"),
+    require("./assets/entity_objectives/ent_obj_static.json"),
+]} />
+
+This configuration ties together the quest stages and objectives.
+
+## Quest Demo
+
+To see how all these elements come together in practice, check out this demonstration of the _**"A Sip of Memories"**_ quest:
+
+<Player url={require("./assets/entity_objectives/quest_demo.webm").default} />
+
+This demo showcases:
+- How players interact with NPCs and their dialogues
+- The visual indicators guiding players to objectives
+- The flow of the quest from start to finish
+
+By implementing [Interact Entity Objectives](../../../adapters/EntityAdapter/entries/quest/interact_entity_objective.mdx) in your quests, you can create rich, interactive experiences that helps guide players to where they need to go.