# SANDBOX.md — Entorno de Pruebas y Simulación (4GatosCoin)

El **Sandbox** es el entorno seguro de pruebas del organismo 4GatosCoin.  
Permite simular gestos, energía, ciclos, temporadas, rituales, semillas, territorio y narrativa sin afectar el estado real del organismo.

Es el laboratorio donde los desarrolladores pueden experimentar, depurar y validar comportamientos.

---

# 1. ¿Qué es el Sandbox?

El Sandbox es:

- un entorno aislado  
- un simulador del organismo  
- un espacio de experimentación  
- una herramienta de depuración  
- un entorno para pruebas de carga  
- un entorno para pruebas narrativas  

No afecta:

- estado global  
- memoria real  
- territorio real  
- avatar real  
- temporadas reales  

---

# 2. Ubicación Técnica

El Sandbox vive en:

```
app/devweb3/sandbox/
```

Y su lógica en:

```
lib/sandbox/
```

---

# 3. Capacidades del Sandbox

## 3.1. Simulación de Gestos
Permite enviar gestos falsos:

- pulso_vocal  
- reflection  
- mirror  
- loop  
- clauseTrigger  
- dropPlay  

## 3.2. Simulación de Energía
Permite:

- generar energía  
- consumir energía  
- simular picos  
- simular caídas  

## 3.3. Simulación de Ciclos
Permite:

- completar ciclos  
- modificar umbrales  
- simular ciclos acelerados  

## 3.4. Simulación de Temporadas
Permite:

- activar temporadas  
- cambiar reglas  
- probar ambientes  

## 3.5. Simulación de Rituales
Permite:

- activar rituales  
- simular participación  
- probar impacto  

## 3.6. Simulación de Semillas
Permite:

- generar semillas  
- forzar rarezas  
- probar distribución  

## 3.7. Simulación de Territorio
Permite:

- expandir zonas  
- modificar dominancia  
- activar zonas  

## 3.8. Simulación de Narrativa
Permite:

- generar ecos  
- generar silencios  
- generar anomalías  
- probar narrativa profunda  

---

# 4. Flujo del Sandbox

```
Simulación → Procesamiento → Impacto Virtual → Visualización → Logs Sandbox
```

### 4.1. Entrada
El Sandbox recibe:

- gestos simulados  
- energía simulada  
- ciclos simulados  
- rituales simulados  
- temporadas simuladas  
- semillas simuladas  
- territorio simulado  
- narrativa simulada  

### 4.2. Procesamiento
El Sandbox ejecuta la lógica real del organismo, pero en un entorno aislado.

### 4.3. Salida
El Sandbox produce:

- estado virtual  
- narrativa virtual  
- logs virtuales  
- visualización OTT virtual  

---

# 5. Panel del Sandbox

Ubicación:

```
app/devweb3/sandbox/
```

Incluye:

- simulador de gestos  
- simulador de energía  
- simulador de ciclos  
- simulador de temporadas  
- simulador de rituales  
- simulador de semillas  
- simulador de territorio  
- simulador de narrativa  
- consola de logs  
- visualización OTT sandbox  

---

# 6. Seguridad del Sandbox

El Sandbox:

- nunca escribe en la base de datos real  
- nunca modifica el estado global  
- nunca altera memoria real  
- nunca afecta avatares reales  
- nunca activa rituales reales  

Todo ocurre en:

```
sandboxState (memoria temporal)
```

---

# 7. Ejemplo de Simulación

### Simular un gesto

```json
{
  "simulate": "gesture",
  "gesture": "pulso_vocal",
  "wallet": "0xFAKE"
}
```

### Resultado

```json
{
  "pointsAdded": 3,
  "energyGenerated": 3,
  "virtualHeartbeat": 92
}
```

---

# 8. Cómo Extender el Sandbox

1. Añadir módulos en:
   ```
   lib/sandbox/
   ```
2. Añadir UI en:
   ```
   app/devweb3/sandbox/
   ```
3. Añadir endpoints virtuales en:
   ```
   app/api/sandbox/
   ```
4. Actualizar documentación si aplica.

---

# 9. Roadmap del Sandbox

- sandbox narrativo avanzado  
- sandbox territorial 3D  
- sandbox de temporadas dinámicas  
- sandbox de rituales combinatorios  
- sandbox de ecos globales  
- sandbox de avatar visual  

---

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