Crear y llevar tu módulo al teléfono

Crea un proyecto, prueba una acción en Studio y exporta el paquete firmado. Después instala ese mismo archivo en la app para probarlo en Android o escritorio.

Instalar el SDK

1. En Módulos, pulsa Descargar SDK y ejecuta el instalador .exe para Windows x64.
2. Completa la instalación y abre Nelkano SDK Studio desde Inicio o el acceso del escritorio.

Incluye Node.js, Java, los tipos y los ejemplos. No necesitas instalar npm, un JDK ni Android Studio para crear módulos JavaScript o TypeScript.

Crear un proyecto

1. Entra en Ajustes → Nuevo módulo.
2. Elige una carpeta para tus proyectos, nombre, identificador y plantilla.

Guarda tus proyectos fuera de la carpeta de instalación. Si prefieres la terminal, abre PowerShell en la carpeta de instalación de Studio y utiliza .\nelkmod.cmd:

El proyecto contiene manifest.json, el código en src y sus recursos. El manifiesto declara nombre, ID, versión, permisos y archivos incluidos. Añade cada archivo nuevo a files; Studio ofrece hacerlo al crearlo.

Probar y exportar desde Studio

1. Guarda el código para actualizar el visor y prueba tu acción.
2. Pulsa Exportar para generar el .nelkmod firmado.
3. Guarda una copia privada de la clave de firma. Las futuras versiones deben conservar la identidad del autor.

Al abrir Studio desde Inicio, la clave de firma está en %LOCALAPPDATA%\Nelkano\SDK\.nelkdev\author.pem. Si abres una carpeta con la CLI, se guarda en .nelkdev/author.pem dentro de esa carpeta. No incluyas la clave en files ni la publiques en Git.

Exportar desde la terminal

Crea primero C:/claves. Usa destinos que todavía no existan para generar las claves y el paquete:

Instalar el archivo en Nelkano

1. Abre Ajustes → General → Módulos → Instalados.
2. Pulsa Importar módulo y elige el archivo .nelkmod.
3. Revisa los permisos y pulsa Instalar.

Para importar una actualización, desactiva primero el módulo. El nuevo archivo debe conservar su ID y la clave del autor.

Instalar desde el catálogo

1. Abre Ajustes → General → Módulos → Explorar.
2. Busca por nombre o sistema y abre la ficha.
3. Pulsa Instalar o Actualizar. La app descarga y verifica el paquete.
4. Revisa el autor, la compatibilidad y los permisos. Pulsa Instalar para aceptarlos.

La verificación comprueba tamaño, SHA-256, firma Ed25519, autor y compatibilidad. La firma identifica al autor y detecta cambios en sus archivos; sigue siendo necesario revisar lo que permite hacer al módulo.

La ficha agrupa la información adicional en Compatibilidad, Versiones y Detalles técnicos. Este último permite copiar identificadores, dependencias e identidad del autor.

En Instalados puedes activar y desactivar módulos opcionales. Desinstalar pide confirmación y conserva sus datos, salvo que marques Eliminar también sus datos. Los de Módulos esenciales vienen con Nelkano y se actualizan con la app.

Publicar una nueva versión

1. Exporta un paquete con el mismo ID y la misma clave de autor.
2. Aumenta la versión X.Y.Z, por ejemplo de 0.1.0 a 0.1.1.
3. En la ficha del catálogo web, pulsa Añadir versión y explica los cambios.
4. Para un módulo público, facilita su enlace directo de descarga. Para Sólo Tester, sube el archivo privado desde una cuenta con permiso de administración de módulos.

El servidor verifica el paquete y conserva las versiones anteriores con sus hashes. Reparar una versión ya registrada exige subir exactamente los mismos bytes.

Cómo recibe la app las actualizaciones

Nelkano comprueba al arrancar y al volver al primer plano, con seis horas entre comprobaciones automáticas. Puedes comprobar antes desde Módulos → Instalados → Comprobar actualizaciones.

Se ofrecen versiones superiores de módulos opcionales, con el mismo autor y compatibles con el SDK y la plataforma actuales. Cuando la app está libre, el aviso permite Ver actualizaciones o Más tarde. También aparece Actualizar módulo en Instalados; no se envía una notificación del sistema operativo.

1. Pulsa Actualizar módulo para abrir la ficha.
2. Si está activo, confirma Desactivar y continuar.
3. Espera a la descarga y verificación.
4. Revisa todos los permisos, incluidos los nuevos, y pulsa Instalar.

Cancelar la descarga o la revisión no instala nada. La actualización conserva los datos y recupera la instalación anterior si falla la sustitución. Gestionar módulo abre su entrada en Instalados cuando corresponde. También puedes actualizar mediante Importar módulo, con el módulo desactivado y la misma clave.

Los esenciales se actualizan con Nelkano. En primer plano, la app revisa el acceso de la cuenta cada minuto: cerrar sesión o perder el rol o permiso retira las actualizaciones privadas.

Distribuir un módulo Sólo Tester

Una cuenta con permiso de administración de módulos puede crear la ficha con acceso Sólo Tester y subir el .nelkmod firmado. El archivo se aloja en almacenamiento privado de la web; la ficha no utiliza repositorio ni admite imágenes públicas.

El acceso se elige al crear la ficha. Sus siguientes versiones deben mantener el ID del módulo y la clave del autor. Se admiten paquetes V1 de hasta 32 MiB, comprobando firma, inventario, tamaño y SHA-256.

Tester y quienes administran módulos ven y descargan tanto los públicos como los reservados. Las demás cuentas y los visitantes sólo ven los públicos. La app utiliza la sesión para autorizar cada descarga privada; cerrar sesión o perder el acceso retira sus fichas, versiones y descargas. La instalación sigue exigiendo verificación y revisión de permisos.

Los módulos públicos usan un enlace externo de descarga y pueden añadir un repositorio opcional.

Elegir JavaScript o TypeScript

Ambos sirven. En TypeScript importa los tipos con import type { Host, Extension } from '@nelkano/sdk'. Para archivos locales usa rutas como ./model.js.

V1 contiene JavaScript y recursos; no incluye Node.js ni librerías npm ejecutables. Revisa files antes de exportar y deja fuera las ROMs y las claves privadas. V2 añade motores nativos compilados, descritos más abajo.

Elegir catálogo o importación local

El catálogo acepta paquetes V1 de hasta 32 MiB y sólo los permisos indicados como admitidos en Permisos y datos. Si tu V1 utiliza otros, como network.external, modules.services, runtime.tasks o emulation.input, distribúyelo para Importar módulo. Los paquetes V2 con motores nativos también requieren importación local.

Preparar tareas persistentes

Una tarea creada con tasks.schedule({id,delayMs,intervalMs?,payload?,background:true}) puede iniciar el módulo y llamar a onBackground(event) sin ejecutar activate().

• Construye el objeto en createModule(host) sin inicializar la interfaz ni depender de variables preparadas en activate().
• Lee la tarea vencida del evento y publica progreso y resultado con tasks.update.
• Guarda puntos de recuperación y evita repetir efectos: el sistema puede volver a intentar una ejecución interrumpida.

Las tareas normales de la app siguen usando onEvent con task-due.

Paquete V2 con un motor compilado

1. Prepara native/build.json con repositorio, commit, receta y hashes de las herramientas.
2. Compila en tu PC con nelkmod engine build ./mi-modulo --target windows-x86_64.
3. Declara el motor y sus artefactos en nativeEngines del manifiesto, con formatVersion:2.
4. Para escritorio, usa nelkmod engine archive para reunir nk-engine-worker(.exe), la DLL/SO y sus dependencias.
5. Ejecuta nelkmod pack para generar el único .nelkmod que importará el usuario.

La ABI, el ejecutor, la plantilla Android y un ejemplo están en native/, dentro de la instalación de Studio.

Fijar las herramientas de compilación

La receta comprueba el commit y los cambios en archivos seguidos por Git. Cada ejecutable debe ser un alias o una ruta absoluta de la lista verificada: se comprueba su hash antes de ejecutarlo, sin buscarlo en PATH. Fija también los compiladores y las herramientas invocadas por CMake.

La compilación sólo se ejecuta al pedirla. Abrir o guardar el proyecto no lanza la receta.

Describir el motor y sus destinos

nativeEngines declara motor, release, protocolo/ABI, descriptor y hash de su JSON canónico. El descriptor recoge sistemas y extensiones, controles, opciones, recursos o BIOS, API gráficas y compatibilidad de estados y almacenamiento.

Cada artefacto indica target, ruta, tamaño y SHA-256: engines/id/android-arm64-v8a.apk, windows-x86_64.zip o linux-x86_64.zip. Incluye sus dependencias.

• Android: declara también packageId, service y certificateSha256.
• Escritorio: declara el entryPoint de la DLL/SO.
• minApi, CPU y runtime describen restricciones; no hacen compatible un binario con otra plataforma.

Límites del paquete V2

El contenedor usa ZIP32 STORE. Manifest y firma van primero; no admite ZIP64, cifrado, enlaces, campos extra ni descriptores de datos. La firma Ed25519 incluye la lista de archivos, tamaños y hashes de todos los destinos.

• Paquete completo: 2 GiB, hasta 16 artefactos y 128 entradas combinadas.
• Artefacto nativo: 1 GiB.
• JavaScript y recursos: 8 MiB por archivo y 32 MiB acumulados.
• Metadatos: 128 KiB por archivo.
• ZIP interior de escritorio: 4096 entradas y 2 GiB expandidos, con rutas y tipos comprobados.

La verificación lee los artefactos por tramos y sólo extrae a disco el destino actual; no los carga en el mapa de bytes de JavaScript. Los paquetes V1 siguen siendo compatibles.

Instalar y recuperar un motor

En Android, prepara un APK sin interfaz, firmado con tu certificado, distinto del de Nelkano. La app comprueba paquete, servicio, certificado y contrato antes de conceder recursos y superficie gráfica.

El motor utiliza un proceso con UID propio. La ruta gráfica emplea un UID normal dedicado, sin permisos de red o almacenamiento. En escritorio, el proceso separado utiliza los permisos del usuario. La firma identifica el código; instalarlo requiere confiar en su autor.

1. Cada versión del APK usa una identidad instalable propia para conservar la anterior.
2. Nelkano guarda la aprobación del módulo, autor y hash antes de abrir el instalador de Android.
3. Al volver, comprueba la instalación y retoma esa aprobación. Si cancelas, conserva la revisión pendiente.
4. Activa el JavaScript después de verificar archivos y conexión inicial con el motor.

Recuperar una instalación anterior no rebaja automáticamente un APK ya instalado. Android sigue gestionando esos APK y su desinstalación. El paquete se puede importar localmente sin publicarlo en el catálogo.