fn_registry/docs/capabilities/gamedev-engine.md

Capability group: gamedev-engine — runtime de juego C++ multiplataforma (PC + WebAssembly)

Cluster de primitivas C++ que forman el núcleo de un runtime de juego 2D portable a escritorio (Windows/Linux/macOS) y navegador (WebAssembly via emscripten). Stack: SDL3 (ventana + input + GL context) + sokol_gfx (render) + miniaudio (audio). Nacido del Issue 0072b.

A diferencia del grupo hermano gamedev-2d (generación de assets 2D con ComfyUI y puente a Godot), este grupo es el motor que ejecuta el juego: el bucle de simulación, la cámara, el input, el render por lotes y el audio. No genera arte; lo consume en tiempo de ejecución.

Tag: gamedev-engine. Filtro: mcp__registry__fn_search query="" tag="gamedev-engine".

Funciones del grupo

ID	Firma corta	Qué hace	Pureza
game_loop_cpp_gamedev	loop_run(SDL_Window*, const LoopCfg&) -> void	Game loop fixed-timestep estilo Glenn Fiedler ("Fix Your Timestep"): desacopla on_fixed_update (dt fijo) de on_render (factor de interpolación), acumulador con cap anti spiral-of-death. Branch automático desktop (while loop) vs __EMSCRIPTEN__ (emscripten_set_main_loop).	impure
input_unified_cpp_gamedev	input_begin_frame(InputState&); input_process_event(InputState&, const SDL_Event*)	Snapshot unificado de input por frame para SDL3: mapea teclado (WASD+flechas), ratón, gamepad y touch a botones lógicos (left/right/up/down/action_a..y/start/back) y ejes analógicos, con flags *_pressed de rising edge limpio.	impure
camera_2d_cpp_gamedev	world_to_screen / screen_to_world(Camera2D, Vec2) -> Vec2; visible_world_rect(Camera2D) -> Rect; view_proj_matrix(Camera2D, float[16])	Cámara ortográfica 2D pura (pos centro, zoom, rotación, viewport): conversiones world↔screen, AABB visible y matriz view-projection 4×4 column-major lista para cualquier renderer. Fast-path sin trig si rotation==0.	pure
sokol_setup_cpp_gfx	make_environment() -> sg_environment; make_swapchain(int w, int h) -> sg_swapchain	Builders puros para inicializar sokol_gfx sobre un GL context creado por SDL3 (no por sokol_app): sg_environment con defaults RGBA8 + depth/stencil y sg_swapchain del default framebuffer del contexto activo.	pure
sprite_batch_cpp_gfx	sprite_batch_create(int cap=4096) -> SpriteBatch; sprite_batch_begin/draw/end	Batched textured quad renderer sobre sokol_gfx: begin/draw/end con auto-flush por cambio de atlas o capacidad llena. Vertex layout pos+uv+color, alpha blending estándar, GLSL 330 / GLES 300. Base de plataformeros, top-down y UI sprites.	impure
audio_engine_cpp_gamedev	engine_init() -> Engine; engine_shutdown(Engine&); engine_set_volume(Engine&, float)	Lifecycle del engine de audio basado en miniaudio (single-header, public domain): inicializa device default, master volume, libera recursos. Cross-platform (WASAPI/ALSA/CoreAudio y WebAudio bajo emscripten). Única TU que define MINIAUDIO_IMPLEMENTATION.	impure
audio_play_cpp_gamedev	sound_load(Engine&, const char*) -> Sound; sound_play/stop/set_volume/destroy(Sound&); play_sound_oneshot(Engine&, const char*, float)	Reproducción de audio sobre fn::audio::Engine: carga con streaming desde disco (wav/mp3/flac/ogg), play/stop/volumen por sonido, y helper fire-and-forget para one-shots sin handle.	impure
build_wasm_cpp_app_bash_infra	build_wasm_cpp_app(app_name, [--no-budget-check]) -> void	Compila una app C++ del registry (cpp/apps/<name>) a WebAssembly via emscripten. Produce build/wasm/<name>/<name>.{html,js,wasm,wasm.gz}. Falla si el gzip supera 2 MB (budget).	impure

Ejemplo canónico (esqueleto de un juego 2D)

Las primitivas se componen así dentro del main() de una app C++ del registry. Cada identificador (fn::game_loop, fn::input, fn::camera2d, fn::gfx, fn::audio) proviene de la función homónima del registry; la app solo aporta la lógica de juego.

// 1. Ventana + GL context con SDL3, sokol_gfx encima (sokol_setup)
sg_setup(...);                              // usa make_environment() del registry
auto swap   = fn::gfx::make_swapchain(W, H);
auto batch  = fn::gfx::sprite_batch_create(4096);
auto audio  = fn::audio::engine_init();
fn::audio::play_sound_oneshot(audio, "assets/music.ogg", 0.6f);

// 2. Estado de cámara e input
fn::game::Camera2D cam{ .pos = {0,0}, .zoom = 1.0f, .viewport = {W, H} };
fn::input::InputState in{};

// 3. Game loop fixed-timestep: simulación e interpolación desacopladas
fn::game::LoopCfg cfg{
  .on_event        = [&](const SDL_Event* e){ fn::input::input_process_event(in, e); },
  .on_fixed_update = [&](float dt){ /* mover entidades usando in.left_pressed... */ },
  .on_render       = [&](float alpha){
      fn::gfx::sprite_batch_begin(batch);
      // draw sprites con cam.view_proj_matrix(...) como transform
      fn::gfx::sprite_batch_end(batch);
  },
};
fn::game::loop_run(window, cfg);

// 4. Distribuir a navegador: build_wasm_cpp_app "<app>" -> build/wasm/<app>/

Fronteras (qué NO cubre)

• Generación de assets (sprites, tiles, VFX): es el grupo hermano gamedev-2d (ComfyUI → post-proceso → Godot). Este grupo solo los renderiza en runtime.
• Física / colisiones / ECS: no incluidos. El on_fixed_update recibe el dt fijo; la simulación la pone la app.
• TileSet / mapas / escenas: no hay sistema de niveles; sprite_batch dibuja quads sueltos.
• App end-to-end consumidora: a fecha de hoy estas primitivas son el núcleo del runtime (Issue 0072b) pero no hay todavía una app C++ que las componga end-to-end (varias están marcadas pendiente-usar). El ejemplo de arriba es el esqueleto previsto, no un binario validado. Cuando exista la primera app, su app.md declarará estas IDs en uses_functions y servirá de validación e2e.

Prerequisitos / notas

• SDL3 para ventana + input + GL context; sokol_gfx (vendored en cpp/vendor/) para render; miniaudio (single-header) para audio.
• Target nativo: GLSL 330. Target WebAssembly (emscripten): GLES 300 — sprite_batch emite ambos shaders.
• build_wasm_cpp_app exige el SDK de emscripten en el entorno y respeta un budget de 2 MB gzip por defecto (--no-budget-check para saltarlo).