IGNI INPUT CORE

IGNI INPUT CORE define los contratos mínimos necesarios para la máxima compatibilidad con el futuro motor de videojuegos IGNI ENGINE.

Este crate no implementa ningún comportamiento concreto.
Su propósito exclusivo es ofrecer interfaces (traits) que garantizan:

• compatibilidad entre múltiples backends de entrada,
• separación estricta entre lectura y mutación,
• comportamiento determinista para el runtime,
• consistencia y seguridad en el editor,
• flexibilidad para futuras extensiones.

IGNI INPUT CORE es la base sobre la cual se construirán los sistemas de entrada del motor, del editor visual, de las herramientas externas y de los backends de cada plataforma.

Estructura general

El sistema se divide en tres capas fundamentales, ordenadas desde el nivel más bajo (sin procesar) hasta el nivel lógico más complejo (acciones y contextos).

Cada capa superior depende únicamente de la inferior, nunca al revés.

1. Raw Layer (Capa 0)

La capa más cercana al sistema operativo o backend real de entrada.

Responsabilidades

• Recibir eventos crudos provenientes del sistema operativo, drivers o crates externos.
• Representar teclas, códigos, estados y eventos en su forma más simple y sin procesar.
• Estandarizar el input de diversas plataformas en un formato común para el motor.

Restricciones

• No procesa ni interpreta eventos.
• No mantiene estado.
• No agrupa, no asigna acciones, no calcula transiciones.
• Su responsabilidad termina en entregar eventos crudos hacia capas superiores.

Traits de la capa

Debido a su naturaleza puramente descriptiva, esta capa define solo traits de estado, sin control mutante.

Ejemplos conceptuales:

• KeyCodeExt
• KeyStateExt
• KeyEventExt

Estos traits exponen metadatos y propiedades estáticas sobre los elementos crudos, pero nunca mutan estado ni establecen relaciones.

2. Processing Layer (Capa 1)

Esta capa recibe los eventos de la Raw Layer y construye a partir de ellos un estado procesado del input.

Ejemplos:

• teclas recién presionadas,
• teclas mantenidas,
• teclas liberadas,
• historial inmediato,
• cálculos de deltas temporales.

Responsabilidades

• Transformar eventos crudos en información utilizable.
• Mantener el estado actual y previo del frame.
• Registrar transiciones.
• Preparar la información para sistemas superiores (acciones y mapeos).

Estructura interna

La capa se divide en dos traits:

a) ProcessingLayerState (solo lectura)

Permite consultar:

• estados de las teclas,
• transiciones,
• historial,
• valores derivados.

No muta nada.

b) ProcessingLayerControl (mutación)

Permite:

• actualizar con nuevos eventos,
• avanzar o reiniciar el estado del frame,
• limpiar transiciones,
• ejecutar resets completos.

Esta separación garantiza seguridad en tiempo de compilación y claridad en la intención de uso.

3. Mapping Layer (Capa 2)

La capa más abstracta y orientada a lógica de juego.
Permite construir esquemas de control basados en acciones, contextos y asignaciones dinámicas.

Ejemplos:

• Acción "Saltar" asignada a Space.
• Acción "Disparar" asignada a Mouse1.
• Contexto "Gameplay" separado del contexto "UI".
• Mapeos distintos para vehículos o cinemáticas.
• Contextos habilitados y deshabilitados dinámicamente.

Responsabilidades

• Resolver Action → Key.
• Resolver Key → Action.
• Registrar, modificar o eliminar acciones.
• Crear, renombrar o eliminar contextos.
• Gestionar habilitación o deshabilitación de contextos.
• Aplicar resets totales o parciales.
• Clonar contextos.
• Permitir introspección profunda mediante traits de estado.

Estructura interna

La capa define dos traits principales:

a) MappingLayerState (solo lectura)

Permite consultar:

• contexto activo,
• lista de contextos,
• lista de acciones,
• bindings,
• acciones por tecla,
• estado de habilitación,
• consistencia del sistema.

Retorna slices y referencias para evitar asignaciones innecesarias.

b) MappingLayerControl (mutación completa)

Permite:

• cambiar de contexto activo,
• añadir o eliminar contextos,
• habilitar o deshabilitar contextos,
• añadir, renombrar o eliminar acciones,
• asignar y desasignar teclas,
• resetear contextos total o parcialmente,
• clonar contextos completos,
• aplicar operaciones globales en todos los contextos.

Esta capa es la base de:

• el editor de IGNI ENGINE,
• las configuraciones de usuario,
• perfiles de control,
• sistemas de accesibilidad,
• mapeo dinámico en runtime (si está permitido).

Filosofía del diseño

IGNI INPUT CORE está diseñado bajo cuatro principios:

1. Separación estricta de responsabilidades
   Cada capa hace solo lo que debe hacer, sin conocimiento innecesario de otras capas.

2. Máximo rendimiento
   La lectura del estado debe ser extremadamente rápida, evitando asignaciones y copias.

3. Extensibilidad total
   Cualquier backend (Windows, Linux evdev, XInput, gamepad, VR) puede cumplir los contratos sin restricciones artificiales.

4. Determinismo y claridad
   Los traits definen explícitamente qué se puede hacer y qué no, evitando ambigüedades entre plataformas.

Estado del proyecto

Este crate define exclusivamente los contratos necesarios para construir:

• backends,
• sistemas de procesamiento,
• el editor,
• el motor en sí.

No contiene implementación alguna.
Las implementaciones se desarrollarán en crates separados, manteniendo el núcleo completamente genérico y desacoplado.

IGNI Trademarks

The names "IGNI", "IGNI Engine", "IGNI Input", "IGNI Game Core", and all associated logos, branding, and visual identity are trademarks of Cristian Valencia.

These trademarks are not licensed under the MIT license that applies to the source code in this repository.

Permitted Use

You may:

• Use IGNI libraries, source code, and APIs in your own projects, including commercial ones.
• Modify and redistribute the code under MIT, as long as you do not use the IGNI trademarks to imply endorsement.

Restricted Use

You may NOT:

• Use the IGNI name or logos for any engine, framework, or product that may be confused with IGNI ENGINE.
• Present modified or forked versions as official IGNI products.
• Use "IGNI" in the name of your engine or tools without written permission.

Allowed Descriptions

You may state factually:

• “This project is based on IGNI Input Core.”
• “This game uses the IGNI Engine.”

Ownership

All rights to the IGNI name, brand, and visual identity belong exclusively to Cristian Valencia.