Runtime Music Player GUI (runtime.gui.createMusicPlayer)

Tipo de Solicitação:
- [x] Nova Feature / API
- [ ] Melhoria de Função Existente
- [ ] Bugfix / Correção
- [ ] Otimização

Status: Pendente de envio

Estágio do Factorio:
- [ ] data-stage (data.lua)
- [x] runtime (control.lua)
- [ ] settings (settings.lua)

Mod / Projeto Solicitante: Workers & Resources Soviet Republic OST, versão 0.0.5

Função/API Solicitada

Uma API reutilizável de GUI para controlar faixas de música do Factorio por jogador, preferencialmente no módulo runtime.gui.

Assinatura sugerida:

local playerMusicGui = LDARuntime.gui.createMusicPlayer(player, {
    name = "unique_music_player_name",
    tracks = {
        { name = "music-prototype-name", caption = { "locale.track-title" } },
    },
    locale = {
        title = { "locale.window-title" },
        open_tooltip = { "locale.open-tooltip" },
        previous = { "locale.previous" },
        play = { "locale.play" },
        next = { "locale.next" },
    },
})

O componente deve oferecer um botão de abertura, seleção de faixa e ações de reproduzir, anterior e próxima. A seleção e a reprodução devem ser individuais por jogador.

Parâmetros e Tipos

• player (LuaPlayer, obrigatório): jogador para o qual criar os controles.
• options.name (string, obrigatório): identificador único do componente e da janela.
• options.tracks (array, obrigatório): faixas com nome do protótipo (string) e legenda (LocalisedString).
• options.locale (table, obrigatório): textos localizados do título da janela, tooltip e ações.
• Opções de janela e de reprodução (table, opcionais): tamanho, posição e parâmetros aceitos por LuaPlayer.play_music.

Retorno Esperado

Um controlador ou descritor do componente com referência à janela/controles e meios documentados para atualizar ou fechar a interface; nil para jogador inválido, seguindo o padrão existente da LDA-LIB.

Necessidade no Mod (Caso de Uso)

Mods que registram faixas ambient-sound precisam oferecer uma forma reutilizável para cada jogador escolher uma faixa e reproduzi-la sem alterar a música dos demais. A montagem de janela, seleção, navegação e despacho de eventos é genérica e pode ser compartilhada entre mods.

Exemplo de Uso Prático

local playerMusicGui = LDARuntime.gui.createMusicPlayer(player, options)

Comportamento em Casos Limite

• Retornar nil ou erro explícito e documentado para jogador inválido, configuração incorreta ou lista de faixas vazia.
• Ignorar índices de faixa fora do intervalo sem interromper o runtime.
• Manter seleção e reprodução isoladas por jogador.
• Evitar sobrescrever handlers globais de eventos registrados pelo mod consumidor.
• Lidar com janela destruída/fechada e com jogadores que saem da partida.

Frequência de Execução

• <input checked disabled type="checkbox"> Sob demanda
• <input disabled type="checkbox"> Frequente
• <input disabled type="checkbox"> Execução em massa

Implementação Temporária (Workaround Atual)

Localização: utils/music-player.lua, registrada pelo control.lua. A solução local cria os controles e despacha os eventos até existir uma API oficial.

Compatibilidade e Dependências

• Factorio: 2.1+
• LDA-LIB: 0.0.17; versão mínima para a API solicitada ainda a definir.
• DLC Space Age:
• <input disabled type="checkbox"> Obrigatório
• <input disabled type="checkbox"> Opcional
• <input checked disabled type="checkbox"> Não aplicável

Observações Técnicas

A versão documentada da LDA-LIB já fornece helpers genéricos de janela e busca de elementos, mas não um componente de music player nem um módulo equivalente. A API deve integrar-se ao sistema de eventos da biblioteca sem substituir handlers do mod consumidor.

Histórico de Implementação

• Versão incorporada: Não disponível.
• API oficial: Não disponível.
• Workaround removido: Não.
• Evidência de solicitação: Não disponível.