realskyrin/ns-game-apple-arm-port

Portabilidad nativa de juegos de NS a Apple ARM

El objetivo es que el código original del juego produzca resultados visibles, operables y guardables en el dispositivo de destino. Aunque la CPU sea ARM64, lo que reduce el trabajo de traducción de instrucciones, no se puede omitir la capa de compatibilidad de ABI del SO, memoria, hilos, gráficos, audio y entrada.

Requisitos de lenguaje y arquitectura

• El núcleo del port debe crearse en Rust (.rs), utilizando un workspace de Cargo que separe el análisis de recursos, la ABI compartida, la reescritura offline, la conversión de shaders y el runtime host. Los proyectos Rust existentes se reutilizan directamente; los módulos nativos existentes en C/C++ se integran a través de límites FFI claros, sin reescribir módulos ya validados por uniformidad del lenguaje. Si el usuario especifica explícitamente otra pila tecnológica, se respeta y se documenta la diferencia.
• Swift se usa para el lanzador y la UI específica de Apple; Objective-C/Objective-C++, C/C++ para los puentes de sistema necesarios o bibliotecas nativas existentes; el ensamblador AArch64 se limita a puntos de entrada, guardado de registros y stubs de llamada; Metal Shading Language (MSL) para programas de GPU. Python/Bash solo orquestan preparación de recursos, compilación, firma y diagnóstico, sin ejecutar rutas críticas de reproducción por fotograma o guest.
• El flujo es: análisis de recursos local → reescritura offline AArch64 → ejecución nativa del código máquina original del juego → compatibilidad Horizon/SDK → grabación de comandos NVN y reproducción con Metal. Se conserva la lógica original del juego; no se reescribe la jugabilidad, demos host o stubs vacíos de API como sustitutos de un port real.
• Antes de comenzar la implementación o reutilizar un port para otro juego, se debe leer architecture-and-workflow.md para determinar los límites de los módulos, la configuración de la versión del juego y la ruta de validación vertical más corta. Esta referencia está extraída de la estructura de port real en Rust/Cargo y no requiere que el proyecto original exista en la máquina local.

Cómo empezar

1. Localizar el repositorio de destino desde el directorio especificado por el usuario o desde el espacio de trabajo actual; los repositorios de referencia solo se leen si el usuario los proporciona o si son detectables en el espacio de trabajo actual, sin asumir rutas del desarrollador local. Leer la descripción del repositorio de destino, el archivo AGENTS.md local, el estado de Git, los puntos de entrada de compilación y el registro de validación más reciente. Primero, confirmar si el usuario desea implementar, diagnosticar o solo evaluar; las tareas de evaluación deben ser de solo lectura.
2. Establecer la matriz de entrada: juego/Title ID, base/actualización/DLC, versión mostrada, arquitectura NPDM, build ID real de los módulos NSO, SO/chip de destino, versión del código fuente, modo de ejecución. La referencia es el contenido real extraído de los módulos, no el nombre del archivo o el nombre del juego para inferir AArch64.
3. Mantener la ruta establecida. Si ya existe una capa de compatibilidad nativa, reutilizar la arquitectura de extracción, reescritura, host y Metal, comparando módulo por módulo; no se deben copiar directamente los parches de direcciones de otros juegos. Para un proyecto nuevo, verificar primero si hay una capa de compatibilidad reutilizable y luego decidir el esfuerzo. La entrada AArch32 no es adecuada para esta ruta de ejecución directa AArch64; buscar la versión adecuada que el usuario ya posea o aclarar que se necesita otra ruta de ejecución.
4. Seleccionar primero una ruta de validación corta y repetible: inicio → título/menú → escena → interacción → salida normal → nuevo proceso cargando partida. Avanzar por etapas, desbloqueando un bloqueo real a la vez, utilizando registros, código e imagen para determinar la causa.

Leer referencias según el problema

• Carga de código, parches, ABI de Horizon, hilos y despliegue en plataformas: leer runtime-and-platforms.md.
• Pantalla negra, artefactos, anomalías en terreno/agua, problemas de shader o rendimiento: leer graphics-and-debugging.md.
• Validación, juicio de progreso, revisión y traspaso: leer validation-and-cases.md. Incluye casos transferibles y límites de evidencia.

Ciclo de implementación

• Primero, registrar la capa donde ocurre el fallo: extracción/identificación → reescritura de instrucciones → carga/reubicación → SDK/servicios → grabación de comandos → reproducción/envío a Metal → ventana real → comportamiento del juego.
• Cada ronda usar una hipótesis falsable, recopilar la evidencia mínima necesaria y luego realizar una reparación local. El diagnóstico está desactivado por defecto, con límites de cantidad/tamaño; las excepciones deben incluir la posición relativa del módulo, la información de la solicitud o recurso, y no pueden filtrar claves.
• Elegir la validación adecuada para la reparación semántica subyacente: equivalencia de instrucciones, diseño de ABI, concurrencia, lectura de vuelta real de la GPU. Después de la verificación estática y la compilación, ejecutar el juego real según el alcance autorizado por el usuario; si el usuario prohíbe las pruebas, solo registrar que no está verificado, sin ejecutar por cuenta propia.
• El código fuente, la compilación, el paquete de instalación, el ID de ejecución, los registros y las capturas de pantalla correspondientes a una versión deben ser vinculables. No se puede usar un registro de un dispositivo antiguo para demostrar el éxito de una nueva compilación.
• Conservar los contraejemplos de diagnóstico y actualizar la conclusión actual. La captura de fotogramas o la ejecución paso a paso pueden alterar la temporización; después de la reparación, volver a probar con un nuevo proceso que tenga el diagnóstico desactivado. No modificar artificialmente la altura del personaje, el color del agua, las colisiones o el progreso del juego para eliminar anomalías superficiales.
• Para servicios, instrucciones o formatos desconocidos, mantener información de fallo clara; solo implementar degradaciones con semántica si se demuestra que la persona que llama permite la degradación. No devolver éxito genérico para ocultar funcionalidad no implementada.

Recursos y entrega

• El paquete fuente, las claves y el firmware se mantienen localmente; no escribir valores de claves en parámetros de comandos, registros o repositorios. No copiar este contenido dentro del skill. Conservar la licencia y los avisos de derechos de autor originales.
• El paquete fuente del usuario es de solo lectura; el contenido extraído, los módulos reescritos, la caché, los archivos y los registros se almacenan en un directorio de datos independiente y que se ignora. Aislar por juego y versión, sin sobrescribir el estado de otros emuladores; una reversión del código fuente no debe eliminar los archivos guardados del usuario.
• La caché debe poder reconocer cambios en el build ID de entrada, la versión del reescritor/convertidor, la plataforma y las opciones de compilación. Las versiones desconocidas o mixtas deben rechazarse antes de entrar en el código guest.
• macOS e iOS/iPadOS se compilan, firman y verifican por separado. Que un script de instalación tenga éxito solo demuestra que esa fase funciona; los resultados de iPhone, iPad, simulador y Mac se informan por separado.
• Una compilación local de iOS puede contener código reescrito del juego original; antes de la entrega o publicación, revisar el contenido del paquete de la aplicación y la licencia, y distribuir solo el contenido que se tenga derecho a distribuir. No subir automáticamente derivados locales.

Informe de finalización: qué se modificó, hasta dónde se ejecutó realmente, a qué compilación y dispositivo corresponde la evidencia, qué limitaciones persisten y qué bloqueo debe validarse a continuación. Evitar porcentajes de finalización no verificables o afirmaciones de "compatibilidad total".