# Economía y red de materiales · Alien Raiders 0.3

**Estado: propuesta de diseño implementada en los datos y la documentación. No es un balance validado en partidas.**

[Abrir matriz interactiva](../matriz.html) · [Matriz completa de objetos](MATRIZ_OBJETOS.md) · [Datos de relaciones](../data/matrix.json)

## Intención

La extracción debe plantear decisiones entre sobrevivir ahora, avanzar el refugio y conservar valor para la próxima incursión. Un objeto no tiene una única etiqueta de «basura»: su utilidad depende del alijo, de los objetivos activos, del equipamiento y de sus rutas de transformación.

La referencia funcional es [Needed Items de ARC Tracker](https://arctracker.io/needed-items): seguimiento de necesidades y búsqueda por procedencia. Alien Raiders conserva su universo, identificadores, objetos, precios y recetas. No se importaron nombres ni ilustraciones del juego de referencia. Excepción decidida el 30-10-2026: el arsenal (armas, niveles, accesorios, munición y Armería) copia la estructura y las cantidades de arcraiders.wiki con nombres y materiales propios; ver [ARSENAL.md](ARSENAL.md).

La versión 0.4 contiene **273 objetos de juego en 29 categorías**, incluidas 26 armas en 9 clases, 12 mochilas, 6 arneses y 38 accesorios ([arsenal](ARSENAL.md)). Los 70 PNG recuperados siguen vinculados a sus fichas. Los identificadores anteriores se conservan. [Auditoría de cobertura y asistente](AUDITORIA_CATALOGO.md).

## Diagrama del ciclo de extracción

```mermaid
flowchart LR
  MAP[Zona y contenedor] --> LOOT[Botín individual]
  LOOT --> STASH[Alijo compartido]
  STASH --> RESERVE[Reservas por objetivos]
  STASH --> REC[Refinería: desmontaje destructivo]
  REC --> MAT[Materiales básicos y componentes]
  MAT --> CRAFT[Estación + nivel + esquema + tasa]
  CRAFT --> GEAR[Equipo y consumibles]
  GEAR --> RAID[Preparar incursión]
  RAID --> MAP
  RESERVE --> GOALS[Mejoras, contratos e investigación]
  GOALS --> UNLOCK[Desbloqueos de progresión]
  UNLOCK --> CRAFT
  STASH --> SELL[Venta del excedente]
  SELL --> FEES[Tasas de taller]
  FEES --> CRAFT
```

Las flechas del ciclo de juego no son recetas reversibles. Cada receta y cada desmontaje tiene entradas y salidas concretas en los datos.

## Jerarquía de recursos

| Capa | Función | Ejemplos propios | Decisión buscada |
|---|---|---|---|
| Botín recuperable | Objetos completos que contienen materiales | Taladro sin Broca, Fuente Militar, Generador Portátil Averiado | Reservar para una mejora o desmontar |
| Básicos | Soporte de la economía inicial | Chatarra Metálica, Tela Rasgada, Cableado de Cobre | Buscar volumen, peso y disponibilidad |
| Refinados | Conversión del botín en fabricación especializada | Polímero Balístico, Muelles de Precisión, Servomotor | Elegir estación y reservar componentes |
| Xeno y flora | Dependencia de rutas peligrosas | Glándula Ácida, Núcleo Alfa, Liquen Pulsante | Decidir cuándo asumir riesgo para progresar |
| Equipo | Resultado consumible o recuperable | Víspera, Espino, Noctil, Coraza Alien | Equipar, guardar repuesto o desmontar |
| Acceso y contratos | Recursos de progresión contextual | Llave del Búnker Sellado, Grabación del Heraldo | Revisar hitos antes de vender |
| Reliquias | Ingreso sin cadena industrial obligatoria | Joyero Musical, Estatuilla de Jade | Vender salvo interés personal o futuras misiones |

## Qué contiene cada ficha

- ID estable, nombre español e inglés y descripción.
- Categoría, rareza, peso, pila y precio unitario de venta en Chatarra.
- Ruta de fabricación cuando corresponde: ingredientes, cantidades, salida por lote, estación, nivel, esquema y tasa.
- Desmontaje cuando corresponde: materiales y cantidades recuperadas por unidad destruida.
- Rutas inversas: qué fabricar con el objeto y de qué objetos recuperarlo.
- Zonas y familias de contenedores de obtención previstas.
- Hitos que consumen el objeto y recomendación de reserva contextual.

«No fabricable» y «no reciclable» son estados de diseño válidos. Un órgano raro puede ser exclusivamente botín; un medicamento consumido no recupera sus ingredientes. No se crean recetas ficticias para rellenar celdas.

## Precios y sumideros monetarios

La moneda se llama **Chatarra**. La **Chatarra Metálica** es un objeto físico diferente: vender una unidad de material entrega la cantidad monetaria indicada en su ficha. Las unidades no son intercambiables automáticamente.

El Núcleo de Segador pasa del antiguo marcador de valor 1 a una venta propuesta de **1.800 Chatarra**. En esta matriz es un material raro, no una segunda moneda. La interfaz de Unreal que todavía lo trate como divisa especial deberá migrarse antes de usar este balance.

`value` es siempre precio de venta por unidad. La matriz calcula también venta por kg; sirve para comparar extracciones, pero no reemplaza el valor estratégico de una llave o un componente reservado. No se han definido precios de compra ni stock de comerciantes.

El coste de oportunidad de ingredientes de un lote es la suma de sus precios de venta. La tasa de fabricación propuesta es:

`tasa = max(5, ceil(1,15 × precio_venta_salida × unidades_salida − valor_venta_ingredientes))`

Se cobra una vez por lote. El coste unitario equivalente es `(valor_ingredientes + tasa) / salida_lote`. No es un precio de compra. La fórmula impide que fabricar y vender inmediatamente genere dinero por encima del valor de venta de sus entradas. También identifica dónde el precio del equipo exige una tasa demasiado alta: esos casos deben revisarse en pruebas, no aceptarse por la fórmula.

La tasa se exporta como `craft.fee` en `items.json`. La implementación del juego debe descontar ingredientes y moneda de forma atómica al fabricar; este repositorio documenta y exporta la regla, pero no contiene ese código de Unreal.

## Reciclaje

Todo desmontaje ocurre en **Refinería NV1**, destruye una unidad del objeto y entrega las cantidades definidas en `recycle`. No consume moneda en esta propuesta. No se permite desmontaje en campo en 0.2.

Las rutas anteriores de flora y reciclables se conservan. Para equipo fabricable se propone recuperar `max(1, floor(cantidad_ingrediente / 4))` por ingrediente del lote de una unidad. Una receta que produzca varias unidades requiere revisar la recuperación por unidad antes de ampliar esta regla. Los consumibles y la munición quedan fuera de esa generación automática.

El generador valida que el valor recuperado de equipo fabricable no supere el valor de sus ingredientes. La tasa no se devuelve. El reciclaje de botín natural puede dar materiales que valgan más que su venta directa: es un incentivo a desmontar, no una ruta de fabricación infinita.

**Orden de decisión recomendado:**

1. Reservar lo que consume el plan activo, incluidos prerrequisitos no terminados.
2. Conservar equipo de uso personal y accesos necesarios.
3. Revisar necesidades futuras de recetas y progresión, aunque no estén seleccionadas.
4. Reciclar excedente si faltan sus materiales y tienes acceso a Refinería NV1.
5. Vender si necesitas moneda o si no compensa el espacio del alijo.

La herramienta nunca denomina automáticamente «seguro» a un objeto solo porque el jugador no haya marcado objetivos.

## Obtención y riesgo

| Riesgo | Zona | Identidad de búsqueda |
|---|---|---|
| 1/4 | Distrito Cero | Equipamiento médico, suministros civiles y primeras rutas de acceso |
| 1/4 | Los Suburbios | Botín doméstico, textiles, herramientas y reliquias |
| 2/4 | Zona Industrial | Componentes, combustible, maquinaria y equipo de taller |
| 2/4 | Los Túneles | Flora contaminada, exploración con oxígeno y dispositivos |
| 3/4 | Puerto Muerto | Suministros militares, equipo avanzado y contacto xeno |
| 4/4 | La Ciudad Caída | Órganos raros, núcleos y final de progresión |

Cada ficha cruza zonas con familias de contenedor: armarios eléctricos, herramientas, maquinaria, botiquines, viviendas, armeros, restos de Segadores o flora. Son **asignaciones de diseño**, no garantías de aparición. No se inventaron coordenadas, porcentajes de caída, rutas GPS ni tiempos de reaparición.

Los datos existentes de zona y botín se mantienen. Los campos vacíos se completan con perfiles explícitos por categoría en `LOCATION_PROFILES`. El diseño de cada mapa debe confirmar o afinar esas asignaciones. El modelo actual no expresa exclusiones entre una zona y un contenedor; las combinaciones de la matriz son candidatas, no puntos de aparición aprobados.

## Progresión propia

Se conservan **42 hitos base** en `data/economy.py`, y se añaden **158 etapas de mejora** en `data/combat.py`. La matriz reúne 200 objetivos planificables:

[Consultar cantidades y prerrequisitos de los 200 objetivos](PROGRESION.md).

- 24 mejoras: tres niveles incrementales para Banco de Trabajo, Armería, Banco de Equipo, Laboratorio Médico, Estación de Explosivos, Estación de Utilidades, Refinería y Dron Recolector.
- Seis proyectos del refugio: aire, agua, energía, huerto, almacenamiento y radio.
- Seis contratos: exploración, clínica, colmena, cadena de mando, rescate y salida.
- Seis investigaciones: tejido, ácido, barrera simbiótica, sinapsis, mando alfa y resonancia.

Los requisitos de un nivel son incrementales: subir del 0 al 3 requiere entregar los niveles 1, 2 y 3; subir del 2 al 3 solo exige el tercero. Cada hito se paga una sola vez. Las recompensas monetarias de contratos e investigación todavía no están fijadas. No se asigna una recompensa inventada al calcular el plan.

Los tres niveles de taller son coherentes con las recetas actuales. Los esquemas continúan siendo un desbloqueo separado. La interfaz distingue el material necesario de la capacidad de fabricar: marca bloqueos de estación o esquema, sin fingir que ya puedes usar una receta.

Las nuevas recetas de nivel 2 y 3 requieren esquema. Como distribución inicial, sus esquemas aparecen en cajas de datos y armarios eléctricos de las zonas asignadas al objeto; la matriz exporta estas fuentes en `blueprint_sources`. No se presupone haber obtenido el esquema al encontrar un arma o un componente.

## Ejemplo propio: del metal al refugio

```mermaid
flowchart LR
  SCR[Chatarra Metálica ×16] --> REF[Refinería NV1: dos lotes + tasas]
  REF --> ALY[Placas de Aleación ×4]
  ALY -->|Consumir 3| GUN[Armería NV1 + tasa]
  SPR[Muelles de Precisión ×2] --> GUN
  FIB[Fibra Sintética ×2] --> GUN
  GUN --> XB[Ballesta Silente ×1]
  BOLT[Dardos de Ballesta] --> XB
  ALY -->|Reservar 1 de las 18 necesarias| STORE[Almacén blindado]
  XB --> DIS[Desmontar una ballesta]
  DIS --> RETURN[Placa ×1 + Muelle ×1]
```

Las cantidades exactas, las tasas calculadas y los demás ingredientes de cada hito se consultan en la matriz; el esquema ilustra las ramas relevantes.

## Cálculo de faltantes

El usuario selecciona hitos, marca los completados e introduce el alijo. El plan reúne prerrequisitos una sola vez. Puede agregar un objeto y una cantidad para fabricar.

En modo directo se muestran los objetos finales que faltan. En modo descompuesto, el cálculo consume primero existencias compartidas, fabrica únicamente el déficit, redondea hacia arriba por tamaño de lote y reutiliza sobrantes dentro del mismo plan. Si un componente no tiene receta, queda como necesidad de botín. No se supone que se puede comprar.

El plan no desmonta automáticamente existencias: hacerlo podría destruir un objeto reservado para otra meta. La ficha muestra las fuentes inversas de reciclaje para que el jugador decida. Las tasas se suman una vez por lote. Los costes materiales son oportunidades de venta y no se suman otra vez a la moneda necesaria.

El alijo y los hitos se guardan localmente en el navegador. El archivo de plan exportado permite conservar un registro; no sincroniza con el juego ni con una cuenta. El presupuesto monetario y la fabricación adicional son controles de la sesión actual.

## Validación y pruebas de balance pendientes

El generador revisa referencias, imágenes, IDs, códigos, cantidades, ciclos de recetas y prerrequisitos. La matriz contiene relaciones de fabricación y desmontaje, precios y fuentes de obtención. El plan se prueba con alijo compartido, sobrantes por lote y prerrequisitos superpuestos.

Antes de dar por definitivo el balance, medir en partidas:

- Minutos por primera cura, arma básica y primera mejora de estación.
- Incursiones por mejora NV2/NV3, tasa de extracción y pérdida de equipo.
- Materiales que bloquean demasiadas recetas frente a materiales sin demanda.
- Tasa monetaria por nivel y proporción del ingreso que absorbe el taller.
- Diversidad de rutas: que exista razón para visitar cada zona y elegir riesgo.
- Valor por kg y presión del alijo: evitar un material óptimo que anule los demás.
- Necesidad de cantidades máximas de reserva para contratos ya terminados.

Durabilidad, reparación y mejoras tienen propuestas de datos en 0.3; su ejecución en Unreal sigue pendiente. No se han fijado tasas de aparición ni recompensas monetarias. Integrarlas exige otra revisión de economía y pruebas de juego.

## Mantenimiento

1. Editar objetos y perfiles en `data/items.py`; editar hitos en `data/economy.py`.
2. Ejecutar `python tools/build_items.py`.
3. El proceso regenera ambos catálogos, JSON/CSV, matriz interactiva y tabla maestra.
4. Ejecutar las pruebas del planificador y revisar los cambios generados.
5. Integrar `items.json` y el cobro de tasas en Unreal por el flujo del proyecto.

`data/matrix.json` es un índice derivado de relaciones, no una segunda fuente manual de recetas. `docs/MATRIZ_OBJETOS.md` y `matriz.html` se regeneran; las reglas de este documento se mantienen a mano.
