# AVATAR_STATE.md — Estado del Avatar Individual (4GatosCoin)

El **Avatar Individual** representa la manifestación personal del usuario dentro del organismo 4GatosCoin.  
Es un reflejo vivo de su actividad, sus gestos, su energía, su narrativa y su evolución.

Este documento describe cómo funciona, cómo se actualiza, cómo se relaciona con otros órganos y cómo debe implementarse.

---

# 1. ¿Qué es el Avatar?

El avatar es:

- la **identidad ritual** del usuario  
- la representación de su energía individual  
- un registro de su evolución  
- un espejo de su narrativa personal  
- un indicador de su impacto en el organismo  

El avatar no es un personaje visual (todavía), sino un **estado vivo** compuesto por datos, memoria y evolución.

---

# 2. Componentes Técnicos

### 2.1. Modelo
El avatar se almacena en:

```
models/Aura.ts
```

Campos típicos:

```json
{
  "wallet": "0x123...",
  "nivel": 3,
  "energiaPersonal": 120,
  "racha": 5,
  "ultimoGesto": 1700000000,
  "gestosTotales": 42,
  "semillas": 4,
  "narrativa": {
    "ecos": 12,
    "silencios": 3,
    "rituales": 1
  }
}
```

### 2.2. Endpoints relacionados
Futuro:

```
/api/avatar
/api/avatar/state
/api/avatar/evolve
```

### 2.3. Panel DevWeb3
Ubicación:

```
app/devweb3/avatar/
```

Funciones:

- ver estado del avatar  
- ver evolución  
- ver rachas  
- ver narrativa personal  
- ver energía individual  

---

# 3. Flujo del Avatar

```
Gesto → Puntos → Energía Personal → Racha → Nivel → Narrativa → Avatar
```

### 3.1. Entrada
El avatar recibe:

- gestos  
- puntos  
- semillas  
- memoria personal  
- energía individual  

### 3.2. Procesamiento
El avatar calcula:

- nivel  
- racha  
- energía personal  
- narrativa  
- hitos personales  

### 3.3. Salida
El avatar afecta:

- memoria viva  
- visualización OTT  
- temporadas  
- rituales  
- territorio (indirectamente)  

---

# 4. Niveles del Avatar

El nivel representa la **evolución personal**.

### 4.1. Cómo se calcula
Factores:

- puntos acumulados  
- gestos totales  
- rachas  
- participación en rituales  
- semillas obtenidas  

### 4.2. Ejemplo de niveles
```
Nivel 1 — Despertar
Nivel 2 — Eco Inicial
Nivel 3 — Pulso Activo
Nivel 4 — Reflejo Vivo
Nivel 5 — Portador del Territorio
Nivel 6 — Memoria Andante
Nivel 7 — Ritmo del Organismo
Nivel 8 — Guardián del Latido
Nivel 9 — Tejedor de Temporadas
Nivel 10 — Avatar del Grito
```

---

# 5. Rachas (Streaks)

Las rachas representan **consistencia ritual**.

### 5.1. Cómo funcionan
Una racha aumenta cuando:

- el usuario ejecuta al menos un gesto por día  

Se rompe cuando:

- pasan 24h sin gestos  

### 5.2. Impacto
Las rachas pueden:

- aumentar puntos  
- generar semillas  
- activar narrativa  
- influir en niveles  

---

# 6. Energía Personal

La energía personal es distinta de la energía global.

### 6.1. Entrada
- puntos  
- gestos  
- rituales  
- ciclos personales  

### 6.2. Salida
La energía personal afecta:

- nivel  
- narrativa  
- avatar visual (futuro)  

---

# 7. Narrativa Personal

Cada avatar tiene una narrativa única basada en:

- ecos personales  
- silencios  
- rituales  
- hitos  
- anomalías  
- temporadas vividas  

Ejemplo:

```json
{
  "ecos": 12,
  "silencios": 3,
  "rituales": 1
}
```

---

# 8. Relación con Otros Órganos

### 8.1. Con Gestos
El avatar es un reflejo directo de los gestos.

### 8.2. Con Puntos
Los puntos alimentan niveles y energía personal.

### 8.3. Con Memoria
La narrativa personal se integra en la memoria viva.

### 8.4. Con Temporadas
Las temporadas pueden redefinir:

- niveles  
- rachas  
- narrativa  
- energía personal  

### 8.5. Con Territorio
El avatar influye indirectamente a través de:

- energía generada  
- participación en rituales  

---

# 9. Ejemplo de Estado de Avatar

```json
{
  "wallet": "0xabc...",
  "nivel": 4,
  "energiaPersonal": 180,
  "racha": 7,
  "gestosTotales": 88,
  "semillas": 6,
  "narrativa": {
    "ecos": 20,
    "silencios": 4,
    "rituales": 2
  }
}
```

---

# 10. Cómo Extender el Avatar

1. Añadir campos en:
   ```
   models/Aura.ts
   ```
2. Crear endpoints en:
   ```
   app/api/avatar/
   ```
3. Añadir lógica en:
   ```
   lib/avatar/
   ```
4. Añadir UI en:
   ```
   app/devweb3/avatar/
   ```
5. Actualizar narrativa si aplica.
6. Actualizar documentación.

---

# 11. Roadmap del Avatar

- avatar visual en OTT  
- niveles dinámicos  
- narrativa generativa  
- ecos personales avanzados  
- rituales individuales  
- temporadas personales  

---

# 12. Licencia
Proyecto interno.  
Acceso restringido a desarrolladores autorizados.