NP2kai PS4
Un port nativo de NP2kai para PlayStation 4, con frontend propio,
biblioteca de juegos, remapeo completo, estados de guardado, teclado USB y diagnóstico.
> [!IMPORTANT]
> Necesitas una **PlayStation 4 compatible con GoldHEN**. Este repositorio no
> incluye BIOS, ROM del PC-98, fuentes del sistema ni juegos.
## Requisitos
### Para instalar y usar
- PlayStation 4 con **GoldHEN** funcionando.
- Un método para instalar paquetes `.pkg`: USB o FTP de GoldHEN.
- Archivos propios del PC-98:
- `bios.rom`
- `itf.rom`
- `sound.rom`
- `font.bmp` **o** `FONT.rom`
- Imágenes de juego compatibles: `.hdi`, `.fdi`, `.d88`, `.hdm` o `.t98`.
### Para compilar
- Linux o macOS.
- [OpenOrbis PS4 Toolchain](https://github.com/OpenOrbis/OpenOrbis-PS4-Toolchain).
- `git`, `clang`, `clang++`, `ld.lld`, `llvm-ar` o `ar`, `make`, `patch`,
`python3` y `curl` si quieres subir el PKG por FTP.
## Instalación rápida
1. Descarga el archivo `.pkg` desde la sección **Releases** del repositorio.
2. Copia el PKG a `hdd:/data/pkg/` mediante FTP o a un USB.
3. Instálalo desde el gestor de paquetes de GoldHEN.
4. Abre **NP2kai PS4** desde el menú principal.
## Primera ejecución
En el primer arranque, el frontend comprueba los archivos necesarios y muestra
la ruta exacta de cualquier elemento que falte.
Copia las BIOS y la fuente a:
```text
/data/np2kai-runtime/system/np2kai/
```
Copia tus imágenes de juego a:
```text
/data/np2kai-runtime/games/
```
Después pulsa **Triángulo** para volver a comprobar y **X** para continuar.
## Funciones principales
### Biblioteca
La biblioteca muestra la lista de juegos a la izquierda y la información del
juego seleccionado a la derecha: formato, tamaño, ruta y perfil de controles.
| Botón | Acción |
|---|---|
| **X** | Abrir el juego seleccionado |
| **Cuadrado** | Editar sus controles |
| **Triángulo** | Volver a escanear la carpeta |
| **Options** | Abrir los ajustes |
### Menú durante el juego
Pulsa **L3 + R3** para abrir la pausa. Esa combinación y el touchpad están
reservados para evitar que un remapeo deje el frontend inaccesible.
Desde la pausa puedes:
- continuar;
- guardar o cargar estados;
- cambiar de disco;
- editar los controles del juego;
- reiniciar la emulación;
- abrir los ajustes;
- volver a la biblioteca.
### Controles y teclado USB
Cada botón del DualShock 4 puede representar una tecla del PC-98. Hay un perfil
global y perfiles independientes por juego, con **104 asignaciones** que cubren
las 101 teclas admitidas por NP2kai y los clics del ratón.
El stick derecho mueve el ratón; R2 y L2 actúan como clics. Un teclado USB
conectado a la PS4 funciona directamente y también puede utilizarse para asignar
teclas dentro del editor.
### Estados de guardado
Hay cuatro ranuras por juego en **Pausa > Estados de guardado**.
| Botón | Acción |
|---|---|
| **X** | Guardar |
| **Triángulo** | Cargar |
| **Cuadrado** | Borrar |
Los estados permanecen después de cerrar y volver a abrir la aplicación.
### Diagnóstico
En **Ajustes > Desarrollador > Diagnóstico** puedes consultar el tiempo empleado
por cada frame, FPS, cola de audio y estado del mando y teclado. También se
escribe una muestra por segundo en:
```text
/data/np2kai-runtime/logs/perf.log
```
### Temas
Incluye cuatro temas: gris, azul pizarra, grafito y medianoche. Se cambian desde
**Ajustes > Interfaz > Tema**.
## Compilar desde el código fuente
Clona el repositorio incluyendo sus submódulos:
```bash
git clone https://github.com/EmiiBytee/np2kai-ps4.git
cd np2kai-ps4
git submodule update --init third_party/NP2kai
```
Define la ubicación de OpenOrbis y ejecuta el script principal:
```bash
export OO_PS4_TOOLCHAIN="$HOME/Dev/PS4/OpenOrbis/PS4Toolchain"
./build-and-deploy.sh
```
El script:
1. comprueba las herramientas y el toolchain;
2. aplica automáticamente el pequeño parche necesario sobre NP2kai;
3. copia desde OpenOrbis los módulos requeridos por el paquete;
4. ejecuta las validaciones de regresión y metadatos;
5. compila el core, el frontend y el PKG.
El resultado será:
```text
IV0000-BREW00984_00-NP2KAIBOOTSTRAP0.pkg
```
La primera compilación del core es la parte más lenta. Por defecto se ejecuta
en un solo proceso para que cualquier error sea legible. Puedes paralelizarla:
```bash
NP2KAI_BUILD_JOBS="$(nproc)" ./build-and-deploy.sh
```
Para compilar y subirlo directamente al FTP de GoldHEN:
```bash
PS4_IP=192.168.1.100 ./build-and-deploy.sh
```
El puerto predeterminado es `2121`. Puedes cambiarlo con `PS4_FTP_PORT`.
Después de clonar, descarga el core fijado por el proyecto:
```bash
git submodule update --init third_party/NP2kai
```
## Estructura del proyecto
```text
.
├── SDL2/ frontend y backend de teclado PS4
├── assets/ iconos y configuración incluida en el PKG
├── docs/ capturas y documentación
├── sce_sys/ icono y metadatos generados del paquete
├── sce_module/ módulos copiados desde OpenOrbis al compilar
├── third_party/NP2kai/ submódulo del core original
├── tools/ validadores, generadores y parche del core
├── Makefile compilación y empaquetado
└── build-and-deploy.sh punto de entrada recomendado
```
No necesitas subir tu copia completa de OpenOrbis ni otra copia independiente de
NP2kai. El primero es una dependencia externa y el segundo se obtiene como
submódulo fijado a una revisión concreta.
## Rutas de datos
```text
/data/np2kai-runtime/
├── config/ configuración global y perfiles
├── games/ imágenes de juego del usuario
├── logs/latest.log registro principal
├── logs/perf.log historial de rendimiento
├── states/ estados de guardado
└── system/np2kai/ BIOS, fuente y configuración de NP2kai
```
## Solución de problemas
El registro principal está en:
```text
/data/np2kai-runtime/logs/latest.log
```
Si un juego llega a arrancar pero muestra un error propio del PC-98, prueba a
borrar este archivo para regenerar el estado de la máquina emulada:
```text
/data/np2kai-runtime/system/np2kai/np2kai.cfg
```
Para informar de un fallo, abre un issue e incluye:
- versión de NP2kai PS4;
- modelo y firmware de la PS4;
- versión de GoldHEN;
- formato de la imagen usada;
- pasos exactos para reproducirlo;
- últimas líneas de `latest.log`.
No adjuntes BIOS, ROM ni imágenes de juegos.
## Notas técnicas
Algunas cosas que costaron unas cuantas horas y conviene dejar documentadas:
- El teclado USB usa `libSceKeyboard`, no el IME.
- `sceUserServiceInitialize` se comparte entre mando, audio y teclado y debe
inicializarse una sola vez.
- `APP_VER` y `VERSION` del `param.sfo` deben usar el formato `XX.YY`.
- `retro_serialize_size()` realiza trabajo equivalente a una grabación completa;
no debe llamarse continuamente.
- El core original no reinicia `firstcall` al descargar un juego. El arreglo se
conserva como `tools/np2kai-reload-fix.patch` y se aplica automáticamente.
## Estado del proyecto
**Versión 1.0.** Probada en consola real con instalación, biblioteca, vídeo,
audio, mando, teclado USB, perfiles, remapeo, estados de guardado y cambio de
disco.
La versión es utilizable y relativamente estable, aunque todavía pueden existir
bugs y casos de compatibilidad no descubiertos.
Consulta [CHANGELOG.md](CHANGELOG.md) para ver el historial completo.
## Licencia y archivos de terceros
El código propio del port —frontend, scripts y herramientas— está disponible
bajo la licencia [MIT](LICENSE).
NP2kai, OpenOrbis, SDL2, libretro-common, Tabler Icons y las tipografías usadas
mantienen sus licencias correspondientes. Consulta [THIRD-PARTY.md](THIRD-PARTY.md).
Las BIOS, ROM, fuentes del PC-98 y juegos **no se distribuyen**.
## Créditos
- [NP2kai](https://github.com/AZO234/NP2kai), desarrollado por AZO234 y basado
en Neko Project II de Yui.
- [OpenOrbis PS4 Toolchain](https://github.com/OpenOrbis/OpenOrbis-PS4-Toolchain).
- GoldHEN.
- [Tabler Icons](https://tabler.io/icons).
- Tipografías Carlito y Poppins.
Proyecto por **Emii**.