fn_registry/cpp/functions/gamedev/audio_play.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, example, tested, tests, test_file_path, file_path, params, output

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	example	tested	tests	test_file_path	file_path	params	output
audio_play	function	cpp	gamedev	0.1.0	impure	sound_load(Engine&, const char*) -> Sound; sound_play/stop/set_volume/destroy(Sound&); play_sound_oneshot(Engine&, const char*, float)	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.	gamedev audio miniaudio	audio_engine_cpp_gamedev			false	error_go_core		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);	false			cpp/functions/gamedev/audio_play.cpp	name desc e Engine inicializado por audio_engine_cpp_gamedev. Si e.ok=false, todas las operaciones son no-op. name desc path Ruta al archivo de audio (relativa al cwd o absoluta). Formatos: wav/mp3/flac/ogg via decoders integrados de miniaudio. name desc s Sound handle. ok=true tras sound_load exitoso. Operaciones tras destroy son no-op. name desc v Volumen 0..1 lineal, multiplicativo con el master del Engine. name desc volume Volumen sugerido para play_sound_oneshot (actualmente delega al master via ma_engine_play_sound; reservado para futura implementacion per-instance).	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.