Guía de uso

Qué es el Funpix Kit

Sistemas de componentes de juego desacoplados de Funpixart: cada componente es funcional por separado, se combina con los demás sin acoplarse (dependencias explícitas por manifiesto, sin ciclos) y se lleva a cualquier juego Godot 4.x.

Todos fueron extraídos de Stremus: El Tercer Despertar (RPG táctico estilo Dofus), que es el ejemplar oro: sus fórmulas, reglas y perfiles reales de producción son el molde. Eso significa que nada aquí es teórico — cada sistema ya sostiene un juego real y sus números por defecto son los de producción.

Principios de diseño (se cumplen en los 11 componentes, y hay un test guardián que los vigila):

• GDScript estáticamente tipado, sin autoloads, sin rutas de contenido escondidas.
• Todo por inyección: RNG, reloj, contexto y reglas de juego entran como parámetros o Callable. Resultado: determinista, reproducible por semilla y testeable headless sin escena.
• Datos, no código: ítems, tablas de botín, diálogos, layouts de equipo, perfiles de balance y de progresión son Resource (.tres). Cambiar reglas no toca código.
• Motivos tipados: las operaciones devuelven &"" (OK) o un motivo (&"no_gold", &"inventory_full", …) — nunca un bool mudo.
• Fixtures en memoria: cada componente trae su testing/*_fixtures.gd con un «hola mundo» canónico, sin depender de contenido del juego.

Requisitos

Instalar un componente

1. Descarga el ZIP del componente desde su página (o desde Descargas). Cada ZIP incluye el componente y sus dependencias con la estructura de carpetas ya correcta.
2. Extrae el ZIP en la raíz de tu proyecto Godot. Quedará así:

tu-juego/
├── project.godot
├── addons/
│   └── fpx/
│       ├── inventory/      ← el componente (código + component.cfg + README + fixtures)
│       ├── items/          ← sus dependencias, incluidas en el ZIP
│       └── stats/
└── tests/                  ← los tests del kit (opcional: bórralos si no los quieres)
    ├── inventory/
    ├── items/
    └── stats/

3. Abre el proyecto (o corre --import en CI). No hay nada que activar: los componentes no son plugins de editor ni autoloads — son clases (class_name) disponibles al instante en cualquier script.

var inv := Inventory.new(30)
var grid := GridMap2D.new()

Verificación opcional: si dejaste la carpeta tests/ y tienes GdUnit4 instalado, corre la suite (sección Correr los tests). Verde = el componente funciona igual que en el kit.

Cómo se combinan

Los componentes viven en capas y declaran sus dependencias en su component.cfg — solo hacia capas iguales o inferiores, sin ciclos y sin dependencias transitivas escondidas:

capa 4   progression ──────────────────── (stats · items · inventory · combat · quests)
                │
capa 3   combat · quests · inventory_ui ─ (grid · stats · items · inventory · loot · ui_kit)
                │
capa 2   inventory ───── (items · stats)
                │
capa 1   items · loot ── (stats)
                │
capa 0   stats · grid · dialog · social · world_sim · ui_kit

Reglas prácticas:

• Puedes llevarte un solo componente de capa 0 (p. ej. grid o dialog) sin nada más.
• Si te llevas uno de capa superior, necesitas sus dependencias — por eso los ZIP ya las incluyen.
• Las suturas entre componentes son tuyas y explícitas: p. ej. Equipment.gear_bonus() (inventory) produce el GearBonus que StatSheet.set_source() (stats) consume. Ningún componente llama al otro a tus espaldas.

Qué configura tu juego

Cada componente funciona sin configurar nada (defaults = producción de Stremus). Cuando quieras tus propios datos, estas son las convenciones:

Y en código (inyección): el gate can_equip de InventoryOps, los efectos de consumible (ConsumableEffects.register), los predicados de world_sim, el context de dialog y qué hace tu juego al sellarse un trade. En sandbox/tests, todos los catálogos y perfiles aceptan set_active() / set_search_dirs() sin tocar disco.

Correr los tests

La suite corre headless por CLI (GdUnit4). En el proyecto del kit — o en el tuyo, si conservaste tests/ y tienes el addon:

$GODOT = "C:\Program Files\Godot_v4.7-stable_mono_win64\Godot_v4.7-stable_mono_win64.exe"

# 1) tras añadir/mover archivos, refresca la caché de clases:
& $GODOT --headless --path . --import

# 2) la suite completa (--ignoreHeadlessMode es OBLIGATORIO):
& $GODOT --headless --path . -s -d --remote-debug tcp://127.0.0.1:0 `
    res://addons/gdUnit4/bin/GdUnitCmdTool.gd --ignoreHeadlessMode -a tests

# un solo componente:  ... -a tests/grid

Gotcha conocido: si un archivo recién copiado da un «Parse Error» inexplicable, falta el --import (la caché de clases está vieja).

El modelo copia + sincronía (de dónde sale el código)

El kit se puebla por copia disciplinada desde Stremus, no por fork:

• Un archivo copiado sin delta jamás se edita en el kit: si hay que arreglarlo, se arregla en Stremus (donde lo respaldan 2000+ tests) y se re-copia.
• Una adaptación del kit (parametrizar, inyectar, generalizar) convierte el archivo en kit-first y queda anotada, con su delta exacto, en el libro de sincronía SYNC.md del repo.
• Los números de balance son contrato: el ejemplo canónico (STR 45 + arma 40 @ nivel 10 → atk_melee == 150) da exactamente lo mismo en el kit y en Stremus, y hay tests anclándolo en ambos lados.

Para ti como consumidor esto significa: cada clase que descargas tiene un origen trazable, tests en dos repos y cero divergencia silenciosa.

Roadmap

Demos en vivo

Cada componente tiene una demo interactiva corriendo en el navegador — el proyecto del kit exportado a Web con Godot 4.7, usando las fixtures reales de cada componente (nada simulado: es la misma API que descargas). Están enlazadas desde cada página de componente y desde el hub de demos. El código de las demos vive en demos/ del repo y NO forma parte de los componentes (los ZIP no lo incluyen).

Preguntas frecuentes

¿Puedo usar un solo componente? Sí — es el punto. Los de capa 0 van solos; los demás llevan sus dependencias dentro del ZIP.

¿Necesito el build mono de Godot? No. El kit es GDScript puro; el proyecto de desarrollo usa el build mono por herencia de Stremus, pero ninguna clase requiere C#.

¿Puedo cambiar los números (fórmulas, costes, rarezas)? Sí, y sin tocar código: son Resource versionados (BalanceProfileDefinition, ProgressionProfile, RarityCatalog…). Los defaults del esquema son los valores de producción de Stremus.

¿Los componentes traen UI? No — a propósito. dialog te da el runtime y tú pintas el panel; inventory te da las operaciones y tú pintas la mochila. La UI llega con ui_kit (FK-7).

¿Cómo reporto un bug? El código sin delta se arregla en Stremus (regla del modelo copia+sync). Anótalo y repórtalo al equipo con el nombre del archivo y el caso que falla — idealmente como test.