BLOX ESL · Embeddable Scripting Language

BLOX Core

La biblioteca embebible de BLOX ESL: una VM con API C que un host nativo carga para ejecutar scripts .blox.

Aplicaciones C/C++, motores como Godot, servicios, simuladores industriales y firmware ESP32-S3. El host mantiene el control del proceso; BLOX aporta reglas y comportamiento modificable sin recompilar.

Ver demos API C

host.c • reglas.blox

reglas.blox

FUNCION evaluar_orden(pedido)
INICIO
  SI (pedido[1].score < 700) ENTONCES
    HOST_AUDIT("revision", "..")
  FIN_SI
  RETORNAR resultado
FINAL_FUNCION

C controla el mundo.
BLOX decide la lógica.

¿Qué es un ESL?

ESL significa Embeddable Scripting Language: un lenguaje pensado para vivir dentro de otra aplicación, sin reemplazarla.

• El host C/C++ administra ciclo de vida, archivos, red, UI, sensores, bases de datos o motor gráfico.
• BLOX define reglas y comportamiento de alto nivel.
• El host llama funciones BLOX cuando necesita una decisión.
• BLOX puede llamar funciones nativas registradas por el host.
• Los datos viajan como números, booleanos, strings, tablas, vectores, matrices y JSON.

Lenguaje de consola	Lenguaje embebible
El script suele controlar todo el programa.	El host controla el ciclo principal.
Ejecuta main y termina.	El host puede llamar funciones muchas veces.
Errores pueden cerrar el proceso.	Los errores vuelven al host como estado diagnosticable.
I/O es terminal, archivos o red.	I/O puede ser escena, motor, UI, audio o datos del host.
La aplicación se adapta al lenguaje.	El lenguaje se adapta a la aplicación.

¿Por qué BLOX ESL?

Pensado para escenarios donde la lógica cambia más rápido que el host:

Host-driven

Es el host quien decide cuándo y cómo se ejecuta el script. La VM no toma control del proceso.

Reglas modificables

Comportamiento, umbrales y flujos viven en scripts .blox. Cambias la regla, no el binario.

Data bridge

Datos vía TABLA, JSON, vectores y matrices. Snapshots sin exponer clases internas.

API C limpia

blox.h integrable desde C, C++, motores y cualquier lenguaje con FFI.

reglas industrialesreglas de negociológica de videojuegosautomatizaciónsimuladoresvalidacionespluginsintegraciones con JSONprototipos

Perfiles de BLOX

BLOX Core es el motor. Alrededor viven varios perfiles según dónde se aloja el runtime. La CLI es una herramienta derivada del Core.

Perfil	Para qué sirve
BLOX Core	Embeber la VM BLOX dentro de un host con `blox.h`. ← producto principal
BLOX Core + JSON	Embeber BLOX en hosts que intercambian datos con JSON.
BLOX ESP32 Core	Usar BLOX como componente ESP-IDF en firmware ESP32-S3.
BLOX Godot	Usar BLOX dentro de Godot mediante GDExtension.
BLOX CLI	Ejecutar programas `.blox` desde terminal usando el mismo lenguaje y runtime.Ver CLI →

Comunicación bidireccional

La integración tiene dos direcciones. Los datos viajan como números, booleanos, strings, TABLAS, vectores, matrices o JSON según el perfil usado.

El host llama funciones BLOX

host.cc

blox_vm_call(
    vm,
    "evaluar_orden",
    argumentos,
    1,
    &resultado
);

reglas.bloxblox

FUNCION evaluar_orden(pedido)
INICIO
    // calcular decision
    RETORNAR resultado
FINAL_FUNCION

BLOX llama funciones C registradas

host.cc

blox_vm_register_native(
    vm,
    "HOST_LOG",
    1,
    BLOX_VALUE_EMPTY,
    host_log,
    NULL
);

reglas.bloxblox

HOST_LOG("regla ejecutada")

Separación de responsabilidades

BLOX pide acciones al host mediante callbacks nativos, sin tocar directamente hardware, red, archivos ni UI. El host decide si acepta, valida, encola o rechaza cada acción.

Ejemplo mínimo de embedding

Host C crea la VM, registra una función nativa, carga un script, ejecuta FUNCION PRINCIPAL y llama una función BLOX.

Host C

host.cc

#include "blox.h"

static BloxStatus host_log(
    BloxVM *vm, const BloxValue *args, size_t argc,
    BloxValue *result, void *user_data
) {
    printf("BLOX dice: %.*s\n",
        (int)args[0].as.string.length,
        args[0].as.string.data);
    result->type = BLOX_VALUE_EMPTY;
    return BLOX_OK;
}

int main(void) {
    BloxVM *vm = blox_vm_create();
    BloxValue result;

    blox_vm_register_native(vm, "HOST_LOG", 1,
        BLOX_VALUE_EMPTY, host_log, NULL);

    blox_vm_load_file(vm, "programa.blox");
    blox_vm_run_main(vm);
    blox_vm_call(vm, "sumar", NULL, 0, &result);

    if (result.type == BLOX_VALUE_NUMBER)
        printf("resultado = %.0f\n", result.as.number);

    blox_vm_destroy(vm);
    return 0;
}

Script BLOX

programa.bloxblox

FUNCION sumar()

FUNCION PRINCIPAL
INICIO
    HOST_LOG("script cargado")
FINAL

FUNCION sumar()
INICIO
    RETORNAR 40 + 2
FINAL_FUNCION

Flujo verificado

C crea la VM.
C registra HOST_LOG.
BLOX llama esa función C.
C ejecuta FUNCION PRINCIPAL.
C llama sumar().
BLOX devuelve 42.

Hosts compatibles

La API pública es C. BLOX ESL se puede linkar con cualquier host capaz de llamar una API C.

C / C++ directos

C consolaC++ puroRaylibSDL2QtwxWidgetsUnreal (módulo C++)Godot (GDExtension)herramientas propias

Lenguajes con FFI

C#/.NET (P/Invoke)Python (ctypes / cffi)Java/Kotlin (JNI / JNA)Node.js / ElectronRust (bindgen)Go (cgo)

Backends y servicios

servidor HTTP en Cmicroservicio de reglasFastAPI + DLLNode/Express + DLL.NET Web API + DLL

Industrial y edge

gateways IoTservicios Windows localessimuladores industrialescontroladores de procesossistemas de alarmamonitoreo

¿Dónde encaja BLOX ESL?

BLOX ESL pertenece a la familia de Lua, JavaScript, Python, Tcl, AngelScript, Squirrel. Apunta a un espacio específico: aplicaciones C/C++ que necesitan reglas legibles, tablas, JSON y callbacks nativos, con sintaxis en español y estilo educativo/operacional.

Lenguaje	Enfoque típico
Lua	Liviano, popular en juegos y mods (WoW addons, Roblox).
JavaScript (V8, QuickJS, Duktape)	Plugins de aplicaciones web/desktop, Electron, automatización.
Python embebido	Automatización, ciencia de datos, plugins (Blender, CAD, VFX).
Tcl	Herramientas EDA, testing, automatización clásica.
Guile / Scheme	DSLs, extensión de aplicaciones GNU.
AngelScript	Sintaxis parecida a C++ para gameplay en motores propios.
Squirrel	Liviano para gameplay y entornos con recursos limitados.
GDScript / Blueprints / GML	Scripting dentro de motores concretos (Godot, Unreal, GameMaker).
BLOX ESL	Reglas industriales, reglas de negocio, simuladores, juegos 2D, validadores. Español, tablas 1-based, JSON, callbacks nativos.

Arquitectura del embedding

Host → VM BLOX → script .blox → TABLA de resultados → host aplica cambios.

Host

C / C++ / motor

BloxVM

crea VM, carga script

script.blox

update / evaluar_*

TABLA

estados devueltos

Host aplica

render, actuador, DB

Host

C / C++ / motor

BloxVM

crea VM, carga script

script.blox

update / evaluar_*

TABLA

estados devueltos

Host aplica

render, actuador, DB

Los errores de BLOX no cierran el proceso host: vuelven como estado diagnosticable via blox_vm_last_error().

host.cc

BloxVM *vm = blox_vm_create();

blox_vm_register_native(
    vm,
    "HOST_EVENTO",
    2,
    BLOX_VALUE_EMPTY,
    host_evento,
    &estado_del_host
);

blox_vm_load_file(vm, "reglas.blox");
blox_vm_run_main(vm);
blox_vm_call(vm, "evaluar_orden", argumentos, 1, &resultado);

blox_vm_destroy(vm);

API C — `blox.h`

blox.h es el contrato público del runtime. Tipos opacos, estados de error como enteros, valores universales y funciones sincrónicas.

Tipos opacos

blox.hc

typedef struct BloxVM BloxVM;
typedef struct BloxTable BloxTable;
typedef struct BloxVector BloxVector;
typedef struct BloxMatrix BloxMatrix;
typedef struct BloxStringVector BloxStringVector;

Estados de error

blox.hc

typedef enum BloxStatus {
    BLOX_OK = 0,
    BLOX_ERROR_INVALID_ARGUMENT,
    BLOX_ERROR_IO,
    BLOX_ERROR_PARSE,
    BLOX_ERROR_RUNTIME,
    BLOX_ERROR_NOT_FOUND,
    BLOX_ERROR_UNSUPPORTED
} BloxStatus;

Valor universal

blox.hc

typedef struct BloxValue {
    BloxValueType type;
    union {
        double number;
        int    boolean;
        BloxStringView   string;
        BloxTable       *table;
        BloxVector      *vector;
        BloxMatrix      *matrix;
        BloxStringVector *string_vector;
    } as;
} BloxValue;

Registrar función nativa

blox.hc

BloxStatus blox_vm_register_native(
    BloxVM *vm,
    const char *name,
    size_t argument_count,
    BloxValueType return_type,
    BloxNativeFunction function,
    void *user_data
);

Reglas de indexación

TABLA y STRING[]

Primer índice = 1

VECTOR y MATRIZ

Primer índice = 0

Estas convenciones siguen la semántica interna de BLOX. Los handles devueltos por la VM son prestados: siguen válidos hasta la siguiente llamada a blox_vm_call() o hasta destruir la VM.

Guía rápida de integración

Incluir blox.h.
Linkar contra libblox_core.a o cargar blox_core.dll.
Crear una VM con blox_vm_create().
Registrar callbacks nativos con blox_vm_register_native().
Cargar el archivo .blox con blox_vm_load_file().
Ejecutar PRINCIPAL con blox_vm_run_main().
Llamar funciones BLOX con blox_vm_call().
Leer resultados con BloxValue, blox_table_get() o JSON.
Destruir la VM con blox_vm_destroy().

Demos integradas

Tres integraciones reales del runtime, cada una con un host C y su archivo .blox.

Gaming

Demo 1

Juego — Godot

Godot 4.6 + GDExtension. player.blox maneja movimiento, ataque, gárgolas, gemas y transición entre niveles.

Ver demo

Manufactura

Demo 2

Industrial

Motor de reglas para planta. Sensores en C, evaluar_planta() en BLOX decide ventilador, bomba, alarmas y paradas.

Ver demo

E-commerce

Demo 3

Reglas de negocio

Motor de reglas para pedidos. evaluar_orden() decide descuentos, impuestos, envío y aprobación.

Ver demo

Estado actual

Ciclo funcional completo de embedding

BLOX ESL tiene funcionando el ciclo end-to-end: cargar runtime, script, inicializar, llamar por frame o por evento, intercambiar tablas y JSON, crear entidades y manejar errores. Las tres demos son la evidencia real de esto.

Una VM activa por proceso, llamadas sincrónicas, API no thread-safe. Decisión intencional para estabilizar primero el contrato embebible.

¿Quieres seguir el progreso de BLOX ESL?

Explora la documentación de BLOX y descarga el intérprete actual mientras evoluciona la versión embebible.

Ver Documentación Descargar BLOX

BLOX Core

¿Qué es un ESL?

¿Por qué BLOX ESL?

Host-driven

Reglas modificables

Data bridge

API C limpia

Perfiles de BLOX

Comunicación bidireccional

Ejemplo mínimo de embedding

Hosts compatibles

C / C++ directos

Lenguajes con FFI

Backends y servicios

Industrial y edge

¿Dónde encaja BLOX ESL?

Arquitectura del embedding

API C — blox.h

Tipos opacos

Estados de error

Valor universal

Registrar función nativa

Reglas de indexación

Guía rápida de integración

Demos integradas

Juego — Godot

Industrial

Reglas de negocio

Estado actual

Ciclo funcional completo de embedding

¿Quieres seguir el progreso de BLOX ESL?

API C — `blox.h`