@battle-racing/br-common-lib 3.4.0 → 3.8.0

package/REFACTOR_README.md

@@ -0,0 +1,185 @@
+# Battle Racing Common Library
+
+## Descripción General
+
+Battle Racing Common Library es una librería TypeScript compartida que proporciona tipos, constantes, datos y utilidades comunes para todos los repositorios del ecosistema Battle Racing. Esta librería actúa como el núcleo central de tipos y definiciones que garantizan la consistencia y interoperatividad entre los diferentes componentes del sistema.
+
+## Arquitectura del Sistema Battle Racing
+
+El ecosistema Battle Racing está compuesto por **3 proyectos principales** que comparten esta librería común:
+
+### 1. **Web App** (Frontend)
+
+- Interfaz de usuario para controladores y espectadores
+- Gestión de juegos, karts y usuarios
+- Comunicación en tiempo real vía WebSockets
+
+### 2. **Backend** (API Server)
+
+- Servidor central que maneja la lógica de negocio
+- Gestión de bases de datos y estado de juegos
+- Coordinación entre todos los componentes del sistema
+
+### 3. **Kart Manager** (Software de Kart)
+
+- **Software instalado en cada kart** (Raspberry Pi)
+- Gestiona módulos de hardware conectados al kart físico
+- Procesa eventos locales y reporta cambios de estado
+- Se comunica con el backend como representante del kart físico
+- **Actúa como la fuente de verdad del estado del kart**
+
+## Estructura de la Librería
+
+### 📁 `src/types/`
+
+Contiene todas las definiciones de tipos TypeScript compartidas:
+
+- **`game/`**: Tipos relacionados con juegos (Race, Battle), estados, rankings
+- **`kart/`**: Definiciones de karts, estados de hardware, escudos
+- **`hardware/`**: Módulos de hardware (speed, screen, RGB, flag, sensors, etc.)
+- **`powerUp/`**: Sistema de power-ups y daños
+- **`socket/`**: Eventos y parámetros de comunicación WebSocket
+- **`gameTrack/`**: Configuración de pistas y checkpoints
+- **`user/`**: Usuarios, roles y permisos
+- **`checkpoint/`**: Sistema de checkpoints para carreras
+
+### 📁 `src/constants/`
+
+Constantes compartidas del sistema:
+
+- Estados de karts y juegos
+- Nombres de módulos de hardware
+- Roles de usuario y permisos
+- Medios y efectos de flags
+
+### 📁 `src/data/`
+
+Datos estáticos del juego:
+
+- **`all-power-ups.ts`**: Definición completa de todos los power-ups disponibles
+- **`all-damages.ts`**: Efectos de daño y sus impactos
+- **`role-definitions.ts`**: Definiciones de roles y permisos
+
+### 📁 `src/utils/`
+
+Utilidades compartidas:
+
+- **`roles.utils.ts`**: Funciones helper para gestión de roles
+
+## Sistema de Juegos
+
+### Tipos de Juego
+
+- **Race**: Carrera tradicional con checkpoints y vueltas
+- **Battle**: Modo batalla con power-ups y daños
+
+### Power-ups Disponibles
+
+La librería incluye un sistema completo de power-ups con diferentes niveles:
+
+1. **Battle Nitro** (Nivel 1): Duplica velocidad temporalmente
+2. **Battle Trap** (Nivel 2): Lanza trampa que ralentiza oponentes
+3. **Battle Shot** (Nivel 3): Dispara proyectil a oponente específico
+4. **Battle Blue Shot** (Nivel 4): Daño al primer lugar
+5. **Battle Shield** (Nivel 4): Escudo protector contra daños
+6. **Battle Pulse** (Nivel 5): Ralentiza a todos los oponentes
+7. **Battle God** (Nivel 5): Poder máximo con velocidad, escudo y ataques
+
+## Sistema de Hardware
+
+### Módulos de Hardware por Kart
+
+Cada kart está equipado con múltiples módulos controlados independientemente:
+
+- **Speed Module**: Control de velocidad del motor
+- **Screen Module**: Pantalla LCD para información del juego
+- **RGB Module**: Iluminación LED RGB
+- **Flag Module**: Banderas y señales visuales
+- **Sound Module**: Sistema de audio
+- **Ball Sensor/Disk Thrower**: Sistema de lanzamiento de discos
+- **Disk Sensor/Ball Shooter**: Sistema de disparo de bolas
+- **Star Laser**: Láseres frontales y traseros
+- **Steering Wheel**: Volante con LED
+- **Emergency Module**: Sistema de parada de emergencia
+
+### Estados de Hardware
+
+Cada módulo tiene estados detallados para monitoreo y control en tiempo real.
+
+## Comunicación WebSocket
+
+La librería define eventos WebSocket para comunicación entre componentes:
+
+### Eventos Hardware
+
+- Control de módulos individuales
+- Suscripción a datos de hardware
+- Configuración de módulos
+
+### Eventos Power-up
+
+- Asignación y activación de power-ups
+- Aplicación de daños
+- Sincronización de estados
+
+### Eventos de Juego
+
+- Actualizaciones de estado de juego
+- Rankings y posiciones
+- Eventos de checkpoints
+
+## Sistema de Roles y Permisos
+
+Implementa un sistema de control de acceso con roles jerárquicos:
+
+- **Super Admin**: Control total del sistema
+- **Admin**: Gestión de juegos y usuarios
+- **Controller**: Control de juegos en ejecución
+- **Viewer**: Solo visualización
+
+## Instalación y Uso
+
+```bash
+npm install @battle-racing/br-common-lib
+```
+
+### Importación de Tipos
+
+```typescript
+import { Game, Kart, PowerUp, GameTrack, SocketHardwareModulesEventsParams } from '@battle-racing/br-common-lib';
+```
+
+### Uso de Constantes
+
+```typescript
+import { gameStatus, FLAG_MEDIA_NAME } from '@battle-racing/br-common-lib';
+```
+
+### Acceso a Datos
+
+```typescript
+import { allPowerUps, allDamages } from '@battle-racing/br-common-lib';
+```
+
+## Desarrollo y Contribución
+
+### Compilación
+
+```bash
+npm run build
+```
+
+### Publicación
+
+```bash
+npm run release:patch  # Para cambios menores
+npm run release:minor  # Para nuevas funcionalidades
+npm run release:major  # Para cambios breaking
+```
+
+### Estructura de Desarrollo
+
+- **TypeScript**: Lenguaje principal
+- **ESM**: Módulos ES modernos
+- **Strict typing**: Tipado estricto en toda la librería
+- **Barrel exports**: Re-exports centralizados para fácil importación

package/br-common-lib.code-workspace

@@ -0,0 +1,19 @@
+{
+	"folders": [
+		{
+			"path": "."
+		},
+		{
+			"path": "../game-manager-backend"
+		},
+		{
+			"path": "../game-manager-webapp"
+		},
+		{
+			"path": "../game-track-manager"
+		},
+		{
+			"path": "../kart-manager"
+		}
+	]
+}

package/dist/constants/hardware/damage.d.ts

@@ -6,4 +6,5 @@ export declare const DAMAGE_EFFECT: {
     readonly STAR_HIT_RIGHT: "Star Hit Right";
     readonly SHOT_HIT: "Shot Hit";
     readonly SHORTCUT: "Shortcut";
+    readonly BLUE_SHOT_HIT: "Blue Shot Hit";
 };

package/dist/constants/hardware/damage.js

@@ -9,4 +9,5 @@ exports.DAMAGE_EFFECT = {
     STAR_HIT_RIGHT: 'Star Hit Right',
     SHOT_HIT: 'Shot Hit',
     SHORTCUT: 'Shortcut',
+    BLUE_SHOT_HIT: 'Blue Shot Hit',
 };

package/dist/constants/index.d.ts

@@ -2,5 +2,7 @@ export * from './checkpoint-type';
 export * from './hardware';
 export * from './kart-status';
 export * from './module-name';
+export * from './payment-provider';
+export * from './payment-status';
 export * from './permission';
 export * from './user-role';

package/dist/constants/index.js

@@ -18,5 +18,7 @@ __exportStar(require("./checkpoint-type"), exports);
 __exportStar(require("./hardware"), exports);
 __exportStar(require("./kart-status"), exports);
 __exportStar(require("./module-name"), exports);
+__exportStar(require("./payment-provider"), exports);
+__exportStar(require("./payment-status"), exports);
 __exportStar(require("./permission"), exports);
 __exportStar(require("./user-role"), exports);

package/dist/constants/payment-provider.d.ts

@@ -0,0 +1,5 @@
+export declare const PAYMENT_PROVIDERS: {
+    readonly STRIPE: "stripe";
+    readonly PAYPAL: "paypal";
+    readonly OTHER: "other";
+};

package/dist/constants/payment-provider.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAYMENT_PROVIDERS = void 0;
+exports.PAYMENT_PROVIDERS = {
+    STRIPE: 'stripe',
+    PAYPAL: 'paypal',
+    OTHER: 'other',
+};

package/dist/constants/payment-status.d.ts

@@ -0,0 +1,7 @@
+export declare const PAYMENT_STATUSES: {
+    readonly PENDING: "pending";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+    readonly REFUNDED: "refunded";
+    readonly CANCELLED: "cancelled";
+};

package/dist/constants/payment-status.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAYMENT_STATUSES = void 0;
+exports.PAYMENT_STATUSES = {
+    PENDING: 'pending',
+    COMPLETED: 'completed',
+    FAILED: 'failed',
+    REFUNDED: 'refunded',
+    CANCELLED: 'cancelled',
+};

package/dist/constants/user-role.d.ts

@@ -1,4 +1,5 @@
 export declare const USER_ROLE: {
     readonly SUPER_ADMIN: "SUPER_ADMIN";
     readonly OPERATOR: "OPERATOR";
+    readonly PLAYER: "PLAYER";
 };

package/dist/constants/user-role.js

@@ -4,4 +4,5 @@ exports.USER_ROLE = void 0;
 exports.USER_ROLE = {
     SUPER_ADMIN: 'SUPER_ADMIN',
     OPERATOR: 'OPERATOR',
+    PLAYER: 'PLAYER',
 };

package/dist/data/all-damages.d.ts

@@ -0,0 +1,2 @@
+import type { Damage } from '../types';
+export declare const allDamages: Damage[];

package/dist/data/all-damages.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allDamages = void 0;
+const constants_1 = require("../constants");
+exports.allDamages = [
+    {
+        name: 'Pulse Hit',
+        target: 'All',
+        sound: 'battle_pulse_damage.mp3',
+        rgbEffect: 'Ray Hit Effect',
+        amount: 1,
+        flagMediaName: constants_1.FLAG_MEDIA_NAME.ELECTROCUTED,
+    },
+    {
+        name: 'Trap Hit',
+        target: 'Any',
+        sound: 'battle_trap_damage.mp3',
+        rgbEffect: 'Ray Hit Effect',
+        amount: 1,
+        flagMediaName: constants_1.FLAG_MEDIA_NAME.OIL_DROP_COLORS,
+    },
+    {
+        name: 'Star Hit Left',
+        target: 'Any',
+        sound: 'battle_star_damage.mp3',
+        rgbEffect: 'Ray Hit Effect',
+        amount: 1,
+        flagMediaName: constants_1.FLAG_MEDIA_NAME.HIT_EFFECT,
+    },
+    {
+        name: 'Star Hit Right',
+        target: 'Any',
+        sound: 'battle_star_damage.mp3',
+        rgbEffect: 'Ray Hit Effect',
+        amount: 1,
+        flagMediaName: constants_1.FLAG_MEDIA_NAME.HIT_EFFECT,
+    },
+    {
+        name: 'Shot Hit',
+        target: 'Any',
+        sound: 'battle_shot_damage.mp3',
+        rgbEffect: 'Ray Hit Effect',
+        amount: 1,
+        flagMediaName: constants_1.FLAG_MEDIA_NAME.HIT_EFFECT,
+    },
+    {
+        name: 'Blue Shot Hit',
+        target: 'First',
+        sound: 'battle_shot_damage.mp3',
+        rgbEffect: 'Ray Hit Effect',
+        amount: 1,
+        flagMediaName: constants_1.FLAG_MEDIA_NAME.HIT_EFFECT,
+    },
+];

package/dist/data/all-power-ups.d.ts

@@ -0,0 +1,3 @@
+import type { PowerUp } from '../types';
+export declare const allPowerUps: PowerUp[];
+export declare const defaultPowerUps: PowerUp[];