Estructura del Proyecto: El Manifiesto Operacional

⚙️ PROTOCOLO DE SUPERVIVENCIA ARQUITECTÓNICA v2.0

La única fuente de verdad sobre cómo se organiza el caos en este estudio. Ahora con soporte para IA, Jules y pipelines modernos.

1. EL ÁRBOL FILOGENÉTICO DEL PROYECTO

La carpeta /Content/ no es un vertedero. Es un ecosistema sagrado. Jerarquía por prefijos numéricos para forzar el orden alfabético y mental. Todo asset sin prefijo es un asset huérfano. Los huérfanos se borran sin aviso.

/Content/
├── 01_Core/                    # Sistema nervioso central. Si esto falla, nada existe.
│   ├── GameModes/              # GameMode, GameState, GameInstance.
│   ├── Controllers/            # PlayerControllers y AIControllers.
│   ├── Inputs/                 # Enhanced Input Actions y Mapping Contexts.
│   ├── Interfaces/             # Blueprint Interfaces (BPI_).
│   ├── GameplayAbilities/      # GAS: Abilities (GA_), Effects (GE_), Attributes (GAS_).
│   └── SaveSystem/             # SaveGame objects y lógica de persistencia.
│
├── 02_Design/                  # Donde la magia se vuelve lógica (y bugs).
│   ├── Blueprints/             # Actores lógicos y componentes (BP_).
│   │   ├── Characters/         # Personajes jugables y NPCs.
│   │   ├── Interactables/      # Objetos con lógica de interacción.
│   │   └── Systems/            # Sistemas transversales (inventario, diálogos...).
│   ├── UI/                     # Widgets (WBP_) y lógica de interfaz.
│   │   ├── HUD/
│   │   ├── Menus/
│   │   └── Components/         # Widgets reutilizables (WBP_Comp_).
│   └── Data/                   # DataTables (DT_), DataAssets (DA_). CERO hardcoding.
│       ├── Tables/
│       └── Assets/
│
├── 03_Art/                     # Lo que el jugador ve (mientras el código llora).
│   ├── Animations/
│   │   ├── Characters/         # AnimBP (ABP_), Montages (AM_), BlendSpaces (BS_).
│   │   └── Props/
│   ├── Audio/
│   │   ├── SFX/                # Sound Cues (SC_) y Waves (SW_).
│   │   ├── Music/
│   │   └── Dialogue/           # Voice lines con nomenclatura DI_NPC_Linea_01.
│   ├── Materials/
│   │   ├── Masters/            # Master Materials (M_) únicamente. Sin clutter.
│   │   ├── Instances/          # Material Instances (MI_). OBLIGATORIO usar MI_.
│   │   └── Functions/          # Material Functions (MF_) reutilizables.
│   ├── Textures/               # T_ con sufijo de mapa: _BC, _N, _ORM, _E, _M.
│   ├── VFX/                    # Niagara Systems (NS_) y Emitters (NE_).
│   ├── Vehicles/
│   └── Characters/             # SK_, Rigs, PhysicsAssets (PA_).
│
├── 04_Environment/             # El escenario de nuestros crímenes.
│   ├── Architecture/           # SM_ estructurales: paredes, suelos, techos.
│   ├── Props/                  # SM_ de mobiliario y detalle.
│   ├── Foliage/                # Meshes y configuraciones de Foliage (FT_).
│   ├── Lighting/               # LUTs, IES profiles, Hdri (HDRI_).
│   └── Maps/                   # Niveles (.umap). L_ obligatorio. Prohibido "Test_Final_V2_REAL".
│       ├── Persistent/         # Niveles maestros (L_Main_).
│       ├── Sublevels/          # Sublevels de streaming (L_Sub_).
│       └── _Testing/           # Mapas de prueba efímeros. Se purgan en cada release.
│
├── 05_AI_Generated/            # 🤖 Assets generados o asistidos por IA.
│   ├── _Review/                # Staging. Todo aquí DEBE ser revisado antes de promoverse.
│   ├── Textures/               # Texturas generadas (T_AIGen_).
│   ├── Concepts/               # Concepts e imágenes de referencia. No van a producción.
│   └── Audio/                  # Audio generado por IA pendiente de revisión.
│
└── 06_Developers/              # Zona de Pruebas Bacteriológicas (Safe Zone).
    ├── Axlfc/
    ├── mitxel2022/
    └── TopperH4rley/

⚠️ Regla de Promoción de Assets: Ningún asset sube directamente de 06_Developers/ o 05_AI_Generated/_Review/ a producción sin pasar por un PR con al menos una revisión. El pipeline de Jules puede automatizar el lint, pero el criterio artístico es humano.

2. REGLAS BACTERIOLÓGICAS DE NOMENCLATURA

El uso de espacios, tildes o la letra "ñ" se considera un acto de sabotaje industrial. Los assets se nombran en inglés. Siempre.

Tipo de Asset	Prefijo	Ejemplo
Blueprint Class	`BP_`	`BP_PlayerController`
Static Mesh	`SM_`	`SM_Concrete_Column_01`
Skeletal Mesh	`SK_`	`SK_MainCharacter`
Texture	`T_`	`T_Brick_Wall_ORM`
Master Material	`M_`	`M_Base_Opaque`
Material Instance	`MI_`	`MI_Concrete_Floor_Dirty`
Material Function	`MF_`	`MF_Triplanar_Blend`
Widget Blueprint	`WBP_`	`WBP_MainMenu`
Level / Map	`L_`	`L_DeepNight_Sublevel_01`
Data Asset	`DA_`	`DA_WeaponStats`
Data Table	`DT_`	`DT_EnemyStats`
Anim Blueprint	`ABP_`	`ABP_PlayerCharacter`
Anim Montage	`AM_`	`AM_Attack_Heavy_01`
Niagara System	`NS_`	`NS_Explosion_Debris`
Sound Cue	`SC_`	`SC_Footstep_Concrete`
Blueprint Interface	`BPI_`	`BPI_Interactable`
Gameplay Ability	`GA_`	`GA_Dash`
Gameplay Effect	`GE_`	`GE_Damage_Fire`
AI Generated Asset	`AIGEN_`	`AIGEN_T_Grunge_BC`

Convención de sufijos de Textura:

_BC — Base Color
_N — Normal Map
_ORM — Occlusion / Roughness / Metallic (canal empaquetado)
_E — Emissive
_M — Mask

Correcto: T_Rock_Base_N, MI_Metal_Rusted_02.
Incorrecto: T Rock Base (1), MI_Metal_Ñoño, texture_FINAL_v3_USE_THIS.

3. CONTROL DE VERSIONES: GIT + SVN — EL ACUERDO DE PAZ

Este studio opera en un modelo híbrido. Git controla código y configuración. SVN/Perforce Locking controla assets binarios de UE5. Mezclar ambos sin criterio es la receta del apocalipsis.

¿Qué va a dónde?

Qué	Sistema	Por qué
Scripts C++, configs, CI/CD, docs	Git	Mergeable, diff legible, PR reviews.
`.uasset`, `.umap`, texturas, audio	SVN + LFS	Binarios no mergeables. Locks obligatorios.
Assets de IA en revisión (`_Review/`)	Git LFS	Ciclo corto de revisión; no necesita lock.

La Mecánica del Lock (Bloqueo SVN)

Adquisición: Antes de mover un solo vértice, DEBES adquirir el Lock en SVN.
Exclusividad: Candado en rojo = ese asset pertenece a otra alma. No lo toques.
Infracción: Modificar sin bloqueo previo es falta administrativa grave. El cron no perdona.
Excepción IA: Assets en 05_AI_Generated/_Review/ no requieren lock hasta su promoción a producción.

The Sunday Purge (La Purga Dominical) 🧹

Cada domingo a las 09:00 AM, un cron job ejecuta svn unlock --force masivo sobre todo el repositorio.

Si tenías algo bloqueado y no subiste los cambios antes de esa hora, el bloqueo desaparecerá. El servidor no tiene sentimientos; yo tampoco.

La Directiva Sandbox (Exención): Todo dentro de 06_Developers/ está exento de bloqueo estricto. Es vuestro jardín de juegos. Los assets en 05_AI_Generated/_Review/ también operan sin lock hasta que sean promovidos.

4. PIPELINE DE IA Y JULES — PROTOCOLO DE AGENTES

Los agentes de IA (Jules, Copilot, Claude) son miembros del equipo con privilegios restringidos. No tienen acceso de escritura directa a producción. Jamás.

Zonas de Operación de Agentes IA

Zona	Acceso IA	Acción humana requerida
`06_Developers/`	✅ Lectura + Escritura	Ninguna. Zona libre.
`05_AI_Generated/_Review/`	✅ Escritura (output)	Revisión + aprobación para promover.
`02_Design/`, `03_Art/`, etc.	⚠️ Lectura únicamente	PR obligatorio para cualquier cambio.
`01_Core/`	🚫 Sin acceso	Cambios manuales exclusivamente.

Flujo de Trabajo con Jules

Task Assignment: Las tareas asignadas a Jules se abren como Issues en Git con la etiqueta agent:jules.
Branching: Jules trabaja siempre en ramas con prefijo jules/ (ej: jules/fix-inventory-logic). Nunca en master o develop.
Output: Todo código generado por Jules incluye comentario de cabecera // AI-ASSISTED: Jules [fecha] para trazabilidad.
Review: PR obligatorio con revisión humana antes del merge. Jules no aprueba sus propios PRs.
Prohibición: Jules no toca 01_Core/, archivos de configuración de CI/CD, ni credenciales. Nunca.

🤖 Regla de Oro de IA: Todo asset o código marcado como AIGEN_ o con comentario // AI-ASSISTED debe tener un propietario humano asignado que sea responsable de su calidad. "La IA lo hizo" no es excusa válida en una post-mortem.

5. PIPELINE CI/CD Y AUTOMATIZACIÓN

El servidor trabaja mientras dormís. Configuradlo bien o sufrid las consecuencias.

Jobs Automáticos Activos

Job	Trigger	Acción
Asset Lint	Push a cualquier rama	Valida nomenclatura de assets. Falla el PR si hay violaciones.
Sunday Purge	Domingo 09:00 AM	`svn unlock --force` masivo. Sin excepciones.
Build Nightly	Diario 02:00 AM	Cook de Development build en servidor. Notificación en Discord si falla.
AI Review Ping	Nuevo archivo en `_Review/`	Notifica al equipo en Discord para revisión pendiente.
Release Build	Tag `v..*` en Git	Cook completo Shipping + upload a distribución interna.

Configuración de Notificaciones: Todos los jobs reportan a Discord (#ci-cd-log). Los fallos de Build Nightly mencionan a @dev-team. Los fallos de Asset Lint bloquean el PR automáticamente.

6. PROTOCOLO DE BRANCHES Y RELEASES

El caos de ramas es el segundo mayor asesino de proyectos indie, justo después de "refactorizar todo desde cero a 3 semanas del deadline".

master                  # Producción. Solo merge desde release/*. Protegida.
develop                 # Integración. Aquí converge todo.
├── feature/xxx         # Nueva funcionalidad. Sale de develop, vuelve a develop.
├── fix/xxx             # Bugfix en develop.
├── hotfix/xxx          # Fix urgente sobre master. Merge a master Y develop.
├── jules/xxx           # Ramas exclusivas de Jules. Nunca merge directo a master.
└── release/vX.X.X      # Preparación de release. Solo bugfixes aquí.

Regla de Merge:

feature/* → develop: PR + 1 review.
release/* → master: PR + 2 reviews + build verde obligatorio.
jules/* → develop: PR + 1 review humano obligatorio.
Merge directo a master: PROHIBIDO. Sin excepciones. Ni en domingo.

7. PERFORMANCE BUDGETS — LOS MANDAMIENTOS DEL RENDERING

Un asset hermoso que destruye el framerate es un asset enemigo. Estos límites son innegociables.

Recurso	Límite por Asset	Límite Global en Escena
Triángulos (Prop Hero)	50.000 tris	—
Triángulos (Prop Secundario)	10.000 tris	—
Triángulos (Personaje Principal)	80.000 tris	—
Textura máxima	2048×2048	VRAM < 2GB en escena
Draw Calls	—	< 1000 en escena activa
Luces dinámicas activas	—	< 8 con sombras activas
Partículas activas (Niagara)	500 partículas	< 5000 total en pantalla

LOD Obligatorio: Todo SM_ con más de 5.000 triángulos debe tener mínimo 3 niveles de LOD configurados. El Asset Lint lo verificará. Un mesh sin LODs es un mesh que no entra en producción.