# Sistema de misiones ## Sistema de misiones El motor carga quests desde YAML y las registra por `questId`. Cada entrada define metadatos, objetivo, frecuencia y reward. El registro vive en memoria para validación rápida. ### Estructura básica ```yaml quests: quest_0001: name: "Caza" description: "Elimina 5 zombis" category: combate frequency: DAILY objective: type: KILL mob: ZOMBIE amount: 5 reward: exp: 50 items: - MATERIAL:EMERALD:2 ``` ### Ejemplo completo de `quests/quests.yml` Este ejemplo mezcla quests diarias, semanales y narrativas. ```yaml quests: quest_0001: name: "Control de plaga" description: "Elimina 5 zombis cerca de la aldea." category: combate frequency: DAILY objective: type: KILL mob: ZOMBIE amount: 5 reward: exp: 50 points: 10 reputation: guardia: 3 items: - MATERIAL:EMERALD:2 quest_0002: name: "Recolección urgente" description: "Reúne 16 de trigo para los mercaderes." category: recoleccion frequency: DAILY objective: type: COLLECT material: WHEAT amount: 16 reward: exp: 40 points: 8 reputation: mercaderes: 2 items: - MATERIAL:BREAD:6 quest_0100: name: "Cacería mayor" description: "Elimina 25 esqueletos durante la semana." category: combate frequency: WEEKLY objective: type: KILL mob: SKELETON amount: 25 reward: exp: 250 points: 40 reputation: guardia: 10 items: - MATERIAL:DIAMOND:2 quest_0200: name: "Habla con el capitán" description: "Presenta el informe al capitán de la guardia." category: historia frequency: DAILY objective: type: INTERACT npc: "captain_01" amount: 1 requirements: reputation: guardia: 25 reward: exp: 30 points: 5 quest_0300: name: "Ronda nocturna" description: "Completa la inspección del perímetro." category: historia frequency: WEEKLY objective: type: INTERACT waypoint: "north_gate" amount: 1 requirements: completed: - quest_0200 reward: exp: 120 points: 20 reputation: guardia: 5 ``` #### Qué muestra este ejemplo * `quest_0001` usa `KILL` con reward mixta. * `quest_0002` usa `COLLECT` para economía básica. * `quest_0100` representa una semanal de alto valor. * `quest_0200` y `quest_0300` enlazan reputación e historia. ### Modelo conceptual Una quest combina cuatro bloques: * **Identidad** — `questId`, nombre y categoría. * **Condiciones** — requisitos para aceptar o mantener activa la quest. * **Objetivo** — regla que produce progreso. * **Reward** — efectos al completar. ### Tipos de objetivos El sistema está pensado para objetivos discretos y acumulativos. * `KILL` — mata entidades válidas. * `COLLECT` — reúne items o materiales. * `INTERACT` — usa NPC, bloques o puntos de interés. Cada tipo expone un evaluador interno. Ese evaluador recibe un evento del juego, valida el contexto y decide si suma progreso. ### Cómo se procesa el progreso El flujo de progreso sigue este orden: 1. Llega un evento del juego. 2. El motor localiza quests activas del jugador. 3. Filtra solo objetivos compatibles con ese evento. 4. Valida cooldowns, party y anti-abuso. 5. Calcula `delta`. 6. Persiste el nuevo progreso. 7. Emite evento interno y, si aplica, completa la quest. ``` Evento Bukkit/Folia -> Resolver jugador y contexto -> Buscar quests activas -> Validar objetivo -> Aplicar delta -> Guardar progreso -> Emitir QuestProgressEvent -> Evaluar completion ``` ### Rewards Una reward puede mezclar varias salidas. * `exp` * `items` * `points` * hooks externos Los hooks externos permiten disparar efectos fuera del núcleo. Ejemplos: economía, rangos o notificaciones. ### Patrones útiles #### Quest diaria simple Úsala para contenido de entrada o repetible. ```yaml quest_1001: name: "Minero del día" category: mineria frequency: DAILY objective: type: COLLECT material: IRON_INGOT amount: 12 reward: points: 12 ``` #### Quest con requisito de reputación Úsala para progresión por facción. ```yaml quest_2001: name: "Servicio de élite" category: faccion frequency: WEEKLY requirements: reputation: guardia: 75 objective: type: KILL mob: PILLAGER amount: 10 reward: points: 50 reputation: guardia: 8 ``` ### Flujo interno de una quest #### `canAccept` Antes de aceptar, el plugin valida: * límite de quests activas * frecuencia y rotación activa * requisitos de reputación o storyline * estado previo del jugador #### Activación Al aceptar, el sistema crea un estado por jugador y quest. Ese estado guarda al menos: * `uuid` * `questId` * progreso actual * marca temporal de aceptación * flags de bonus o cooldown #### Tracking El tracking ocurre por evento. No requiere escaneo global continuo. Esto reduce coste y mantiene buen comportamiento con muchas quests definidas. #### Finalización Cuando el progreso alcanza el objetivo: 1. se marca la quest como completada 2. se entregan rewards 3. se actualizan puntos o reputación 4. se emiten eventos y salidas externas ### Diseño recomendado * Usa categorías claras para filtros y GUI. * Mantén objetivos simples y rewards previsibles. * Reserva storylines para cadenas largas y narrativas. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://camiladev.gitbook.io/documentation/quests/guia-de-administracion/sistema-de-misiones.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.