egutierrez
a27dcc028c
El doctor reportaba el dominio gamedev en doble FAIL: el tag plano `gamedev` (44 funciones) como `ungrouped_candidate` y la pagina `gamedev-2d.md` como `doc_orphan`. Causa raiz: el INDEX declaraba `[gamedev](gamedev-2d.md)` y el auditor solo registra el slug cuando label==target, asi que ni casaba la pagina ni declaraba el tag. Al revisar las 44 funciones habia dos clusters reales bajo el mismo tag, asi que se separan en dos grupos honestos: - gamedev-2d (tag canonico): 31 builders de workflow ComfyUI + 5 de apoyo (post-proceso + puente a Godot) = 36. Se elimina el tag plano `gamedev` de los builders (ya tenian `gamedev-2d`) y se reemplaza por `gamedev-2d` en las de apoyo. - gamedev-engine (grupo nuevo, pagina madre nueva): runtime de juego C++ multiplataforma (SDL3 + sokol_gfx + miniaudio, Issue 0072b) = 8. Game loop, camara 2D, input unificado, sprite batch, setup render/audio, build wasm. El tag plano `gamedev` queda eliminado (count 0). INDEX corregido: fila gamedev-2d con label==target y conteo 36 + fila nueva gamedev-engine (8). Verificacion: `fn index` + `fn doctor capabilities` -> ambos grupos OK (declared_in_index=yes, doc_exists=yes, sin issues); `gamedev` plano = 0. Solo se modifico el campo `tags` de los .md, ningun archivo de codigo. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
63 lines
3.0 KiB
Markdown
63 lines
3.0 KiB
Markdown
---
|
|
name: audio_play
|
|
kind: function
|
|
lang: cpp
|
|
domain: gamedev
|
|
version: "0.1.0"
|
|
purity: impure
|
|
signature: "sound_load(Engine&, const char*) -> Sound; sound_play/stop/set_volume/destroy(Sound&); play_sound_oneshot(Engine&, const char*, float)"
|
|
description: "Reproduccion de audio sobre fn::audio::Engine: carga sonidos con streaming desde disco (wav/mp3/flac/ogg), play/stop/volumen por sonido, y helper fire-and-forget para one-shots sin handle. Cross-platform via miniaudio. Issue 0072b — runtime gamedev nucleo."
|
|
tags: [gamedev-engine, audio, miniaudio]
|
|
uses_functions: ["audio_engine_cpp_gamedev"]
|
|
uses_types: []
|
|
returns: []
|
|
returns_optional: false
|
|
error_type: "error_go_core"
|
|
imports: []
|
|
example: |
|
|
fn::audio::Engine eng = fn::audio::engine_init();
|
|
fn::audio::Sound bgm = fn::audio::sound_load(eng, "assets/bgm.ogg");
|
|
fn::audio::sound_set_volume(bgm, 0.5f);
|
|
fn::audio::sound_play(bgm);
|
|
// SFX one-shot:
|
|
fn::audio::play_sound_oneshot(eng, "assets/jump.wav");
|
|
// ...
|
|
fn::audio::sound_destroy(bgm);
|
|
fn::audio::engine_shutdown(eng);
|
|
tested: false
|
|
tests: []
|
|
test_file_path: ""
|
|
file_path: "cpp/functions/gamedev/audio_play.cpp"
|
|
params:
|
|
- name: e
|
|
desc: "Engine inicializado por audio_engine_cpp_gamedev. Si e.ok=false, todas las operaciones son no-op."
|
|
- name: path
|
|
desc: "Ruta al archivo de audio (relativa al cwd o absoluta). Formatos: wav/mp3/flac/ogg via decoders integrados de miniaudio."
|
|
- name: s
|
|
desc: "Sound handle. ok=true tras sound_load exitoso. Operaciones tras destroy son no-op."
|
|
- name: v
|
|
desc: "Volumen 0..1 lineal, multiplicativo con el master del Engine."
|
|
- name: volume
|
|
desc: "Volumen sugerido para play_sound_oneshot (actualmente delega al master via ma_engine_play_sound; reservado para futura implementacion per-instance)."
|
|
output: "Sound con impl=ma_sound* y ok=true en sound_load exitoso; ok=false ante cualquier fallo (engine no listo, malloc, decoder). play_sound_oneshot no devuelve handle — el sonido se gestiona internamente por el engine."
|
|
---
|
|
|
|
# audio_play
|
|
|
|
Reproduccion de audio one-shot y streaming sobre `fn::audio::Engine`. Wrapper minimo de la API `ma_sound` de miniaudio.
|
|
|
|
## Estructura `Sound`
|
|
|
|
Handle opaco con `impl` (apunta a `ma_sound`) y `ok` (bool). Gestion explicita: cada `sound_load` requiere `sound_destroy` para liberar (no hay RAII porque mantenemos `-fno-exceptions` y compat con structs trivial).
|
|
|
|
## Patrones de uso
|
|
|
|
- **BGM / loops largos:** `sound_load` + `sound_play`. Por defecto miniaudio hace streaming desde disco (no carga todo a memoria).
|
|
- **SFX cortos:** `play_sound_oneshot` — fire-and-forget, sin handle, ideal para clicks, jumps, hits.
|
|
- **SFX repetidos con control:** `sound_load` + `sound_play` cada vez. Para concurrent voices del mismo sample, considerar `ma_sound_init_copy` (no expuesto aun).
|
|
|
|
## Notas
|
|
|
|
- `play_sound_oneshot` recibe `volume` como hint pero actualmente delega al master del engine. Iterar si el caller real lo necesita.
|
|
- `sound_load` con `path=NULL` o engine no listo devuelve `Sound{nullptr, false}` — siempre comprobar `ok` antes de operar.
|