Flujo de fallo — Easy Chapter Generator

Contrato de fallo explícito

El sistema no deduce una derrota por salud, tiempo, muerte del jugador ni por un objetivo que no avanza. Un script del juego debe llamar a ChapterManager.TryFailCurrentChapter(reason). La llamada solo se acepta cuando el Manager está preparado, existe un capítulo activo y no hay una transición de escena en curso.

Solo eventos

Aceptar el fallo cambia los estados y emite notificaciones. No carga una escena, no restaura un checkpoint, no reposiciona al jugador, no guarda Failed y no muestra una interfaz automáticamente.

Resultados de la solicitud

Resultado	Cuándo aparece	Respuesta recomendada
`Failed`	El capítulo estaba Active y se aceptó el fallo.	Permite que los receptores apliquen la política del juego.
`ManagerNotReady`	La inicialización aún no terminó.	Espera a On Manager Ready.
`NoActiveChapter`	No hay capítulo actual.	Revisa la selección inicial.
`TransitionInProgress`	Ya se está cargando otra escena.	Ignora la solicitud y no abras otro flujo de derrota.
`ChapterNotActive`	El capítulo está Completed, Failed o Not Started.	No repitas el fallo histórico.

Orden de estados y eventos

Validación

El Manager rechaza estados no válidos sin efectos.

Estado

El Chapter pasa a Failed; el objetivo activo o en espera pasa a Failed.

Evento tipado

ChapterFailed recibe ChapterFailureInfo con Chapter, Objective y reason.

UnityEvent

On Failure se invoca sin parámetros para receptores del Inspector.

Política externa

El juego decide mostrar UI, reintentar, recargar o cambiar de escena.

Prueba reproducible

1
Crea un capítulo con un objetivo activo y ejecuta la escena.
2
Añade un botón de prueba que llame a un script con TryFailCurrentChapter("manual_test").
3
Conecta Manager > Lifecycle Events > On Failure a un panel desactivado para mostrarlo.
4
Suscríbete también a ChapterFailed si necesitas leer el motivo o el objetivo afectado.
5
Pulsa el botón una vez. Confirma Chapter Failed, Objective Failed, un evento tipado y un UnityEvent.
6
Púlsalo otra vez. Debe devolver ChapterNotActive y no emitir eventos nuevos.

Diseñar la recuperación

Después de Failed, el juego puede llamar a TrySelectChapter, ReloadCurrentScene(true), TransitionToScene o a su propio cargador. Elige una sola política y ejecútala desde el receptor de fallo. HandleFailure se conserva por compatibilidad con UnityEvents antiguos, pero su parámetro solo se reenvía como motivo y ya no selecciona un punto de reinicio.

Los estados Active y Failed son transitorios y no se restauran como progreso histórico. Consulta Persistencia del progreso.

Errores frecuentes

On Failure no se ejecuta

Registra el valor devuelto. Si no es Failed, la solicitud fue rechazada antes de los eventos.

La escena no se recarga

Es el comportamiento previsto. Añade una política externa y llama a la transición elegida.

Se muestran dos pantallas

Comprueba que no respondes a la vez a ChapterFailed y On Failure con la misma consecuencia.

El fallo reaparece al cargar

El producto no persiste Failed. Busca un estado propio del juego o una suscripción duplicada.

Solicitar un fallo explícito del capítulo

Dónde colocarlo: Añade este componente al objeto del proyecto que detecta la derrota del jugador.
Cuándo llamarlo: Llama una sola vez a RequestPlayerDefeat cuando la condición de derrota sea definitiva.
Comportamiento: Comprueba ChapterFailureResult. Una solicitud rechazada no invoca ChapterFailed ni OnFailure y nunca recarga una escena.

using System;
using System.Collections;
using System.Collections.Generic;
using OverFuture.ChapterObjectiveSystem.Chapters;
using OverFuture.ChapterObjectiveSystem.Events;
using OverFuture.ChapterObjectiveSystem.Objectives;
using OverFuture.ChapterObjectiveSystem.Persistence;
using OverFuture.ChapterObjectiveSystem.Progression;
using UnityEngine;

public sealed class FailureRequestExample : MonoBehaviour
{
    public ChapterFailureResult RequestPlayerDefeat()
    {
        ChapterManager manager = ChapterManager.Instance;
        return manager != null
            ? manager.TryFailCurrentChapter("player_defeated")
            : ChapterFailureResult.ManagerNotReady;
    }
}

Mostrar una pantalla de muerte del proyecto

Dónde colocarlo: Añade el componente al controlador de interfaz y asigna el GameObject inactivo de la pantalla de muerte.
Cuándo llamarlo: La pantalla aparece únicamente después de que ChapterFailed confirme el estado final de fallo.
Comportamiento: Este ejemplo solo muestra la interfaz. El bloqueo de entrada, la animación, la política de reinicio y la accesibilidad pertenecen al proyecto.

using System;
using System.Collections;
using System.Collections.Generic;
using OverFuture.ChapterObjectiveSystem.Chapters;
using OverFuture.ChapterObjectiveSystem.Events;
using OverFuture.ChapterObjectiveSystem.Objectives;
using OverFuture.ChapterObjectiveSystem.Persistence;
using OverFuture.ChapterObjectiveSystem.Progression;
using UnityEngine;

public sealed class DeathScreenExample : MonoBehaviour
{
    [SerializeField]
    private GameObject deathScreen;

    private ChapterManager manager;

    private void OnEnable()
    {
        manager = ChapterManager.Instance;
        if (manager != null)
        {
            manager.ChapterFailed += ShowDeathScreen;
        }
    }

    private void OnDisable()
    {
        if (manager != null)
        {
            manager.ChapterFailed -= ShowDeathScreen;
        }
    }

    private void ShowDeathScreen(ChapterFailureInfo information)
    {
        if (deathScreen != null)
        {
            deathScreen.SetActive(true);
        }
    }
}

Reiniciar de forma explícita después de un fallo

Dónde colocarlo: Colócalo en el controlador de la pantalla de muerte y llama a RememberFailure desde el receptor tipado del fallo.
Cuándo llamarlo: Invoca TryRestartFailedChapter desde el botón Reiniciar del jugador.
Comportamiento: El reinicio es una política explícita. Se rechaza durante una transición o si no se ha registrado el ID exacto del capítulo fallido.

using System;
using System.Collections;
using System.Collections.Generic;
using OverFuture.ChapterObjectiveSystem.Chapters;
using OverFuture.ChapterObjectiveSystem.Events;
using OverFuture.ChapterObjectiveSystem.Objectives;
using OverFuture.ChapterObjectiveSystem.Persistence;
using OverFuture.ChapterObjectiveSystem.Progression;
using UnityEngine;

public sealed class RestartAfterFailureExample : MonoBehaviour
{
    private string failedChapterId = string.Empty;

    public void RememberFailure(ChapterFailureInfo information)
    {
        failedChapterId = information.Chapter != null
            ? information.Chapter.Identifier
            : string.Empty;
    }

    public bool TryRestartFailedChapter()
    {
        ChapterManager manager = ChapterManager.Instance;
        return manager != null && !manager.IsTransitioning &&
               !string.IsNullOrWhiteSpace(failedChapterId) &&
               manager.TrySelectChapter(failedChapterId);
    }
}