As principais classes Lua

Muitas das principais classes do MAME usadas para implementar a emulação de uma sessão, estão disponíveis para os scripts Lua.

Notificador da assinatura

Envelopa a classe util::notifier_subscription do MAME, faz o gerenciamento de uma assinatura numa notificação de difusão.

Métodos

subscription:unsubscribe()

Faz a remoção da notificação das assinaturas . A assinatura se torna inativa e nenhuma outra notificação será recebida.

Propriedades

subscription.is_active (somente leitura)

Um booleano que indica se a assinatura está ativa. A assinatura se torna inativa depois que a assinatura for explicitamente cancelada ou caso o notificador subjacente seja destruído.

Attotime

Encapsula a classe attotime do MAME, o que representa um intervalo de tempo de alta precisão. Os valores attotime suportam a adição e a subtração com outros valores attotime, assim como a multiplicação e a divisão por números inteiros.

Instanciação

emu.attotime()

Cria um valor attotime representando zero (ou seja, sem tempo decorrido).

emu.attotime(segundos, attosegundos)

Cria um attotime com as partes inteiras e fracionárias específicas.

emu.attotime(attotime)

Cria uma cópia de um valor attotime existente no momento.

emu.attotime.from_double(segundos)

Cria um valor attotime representando um número específico em segundos.

emu.attotime.from_ticks(períodos, frequência)

Cria um attotime representando um número específico dos períodos da frequência informada em Hertz.

emu.attotime.from_seconds(segundos)

Cria um attotime representando um número inteiro específico em segundos.

emu.attotime.from_msec(milissegundos)

Cria um attotime representando um número inteiro específico em milissegundos.

emu.attotime.from_usec(microssegundos)

Cria um attotime representando um número inteiro específico em microssegundos.

emu.attotime.from_nsec(nanossegundos)

Cria um attotime representando um número inteiro específico em nanossegundos.

Métodos

t:as_double()

Retorna o intervalo de tempo em segundos como um valor de ponto flutuante.

t:as_hz()

Interpreta o intervalo como um período e retorna o valor correspondente da frequência em Hertz como um ponto flutuante. Retorna zero caso t.is_never seja verdadeiro. O intervalo não deve ser zero.

t:as_khz()

Interpreta o intervalo como um período e retorna o valor correspondente da frequência em quilo hertz como um ponto flutuante. Retorna zero caso t.is_never seja verdadeiro. O intervalo não deve ser zero.

t:as_mhz()

Interpreta o intervalo como um período e retorna o valor correspondente da frequência em mega hertz como um ponto flutuante. Retorna zero caso t.is_never seja verdadeiro. O intervalo não deve ser zero.

t:as_ticks(frequência)

Retorna o intervalo como um número inteiro em períodos da frequência definida. O valor da frequência é definida em Hertz.

Propriedades

t.is_zero (somente leitura)

Um booleano que indica se o valor não representa um tempo transcorrido.

t.is_never (somente leitura)

Um booleano que indica se o valor for maior que a quantidade máxima de segundos inteiros que possam ser representados (tratados como um tempo inalcançável no futuro ou num estouro).

t.attoseconds (somente leitura)

A fração do intervalo dos segundos em atossegundos.

t.seconds (somente leitura)

A quantidade de segundos inteiros no intervalo.

t.msec (somente leitura)

A quantidade de milissegundos inteiros na porção de segundos fracionários do intervalo.

t.usec (somente leitura)

A quantidade de microssegundos inteiros na porção de segundos fracionários do intervalo.

t.nsec (somente leitura)

A quantidade de nanossegundos inteiros na porção de segundos fracionários do intervalo.

O gerenciador de sistema do MAME

Encapsula a classe mame_machine_manager do MAME que contém o sistema em execução, o gerenciador da IU e os outros componentes globais.

Instanciação

manager

O gerenciador do sistema do MAME está disponível como uma variável global no ambiente Lua.

Propriedades

manager.machine (somente leitura)

O sistema em execução para a sessão da emulação atual.

manager.ui (somente leitura)

O gerenciador da IU para a sessão da emulação atual.

manager.options (somente leitura)

As luascript-ref-emuopts para a sessão da emulação atual.

manager.plugins[ ] (somente leitura)

Obtém informações sobre o plug-in Lua que estão presentes, indexados por nome. Os métodos do índice obtém at e index_of com complexidade O(n).

O sistema em execução

Encapsula a classe running_machine do MAME que representa uma sessão da emulação. Ele fornece acesso aos outros principais objetos que implementam uma sessão da emulação, bem como a árvore dos dispositivos emulados.

Instanciação

manager.machine

Obtém a instância do sistema em execução para a sessão de emulação atual.

Métodos

machine:exit()

Agenda o encerramento da sessão da emulação atual. Isso irá retornar ao menu da seleção do sistema ou encerrar o aplicativo, dependendo de como ele foi iniciado. Este método retorna imediatamente antes que o encerramento do programada ocorra.

machine:hard_reset()

Agenda uma reinicialização a frio. Isso é implementado destruindo a sessão da emulação e iniciando outra sessão para o mesmo sistema. Este método retorna imediatamente antes que a reinicialização programada aconteça.

machine:soft_reset()

Agenda uma reinicialização suave. Isso é implementado chamando o método da redefinição do dispositivo principal, que é propagado pela árvore dos dispositivos. Este método retorna imediatamente antes que a reinicialização programada aconteça.

machine:save(nome_do_arquivo)

Agenda o salvamento do estado do sistema no arquivo informado. Caso o nome do arquivo seja um caminho relativo, ele será considerado relativo ao primeiro diretório do estado de salvamento configurado. Este método retorna imediatamente antes que o estado do sistema seja salvo. Caso este método seja chamado quando uma operação de salvar ou de carregar já esteja pendente, a operação pendente anterior será cancelada.

machine:load(nome_do_arquivo)

Agenda o carregamento do estado do sistema a partir do arquivo informado. Caso o nome do arquivo seja um caminho relativo, os diretórios configurados para do estado de salvamento serão pesquisados. Este método retorna imediatamente antes que o estado do sistema seja salvo. Caso este método seja chamado quando uma operação de salvar ou de carregar já esteja pendente, a operação pendente anterior será cancelada.

machine:popmessage([msg])

Exibe uma mensagem pop-up para o usuário. Caso a mensagem não seja informada, a mensagem de pop-up exibida no momento (caso haja) ficará oculta.

machine:logerror(msg)

Grava a mensagem no log de erros do sistema. Isso pode ser exibido numa janela do depurador, gravado num arquivo ou gravado na saída de erro predefinida.

Propriedades

machine.time (somente leitura)

O tempo decorrida da emulação para a sessão atual assim como em attotime.

machine.system (somente leitura)

os metadados do driver do sistema para o sistema atual.

machine.parameters (somente leitura)

O gerenciador dos parâmetros para a sessão da emulação atual.

machine.video (somente leitura)

O gerenciador de vídeo para a sessão da emulação atual.

machine.sound (somente leitura)

O gerenciador do áudio para a sessão da emulação atual.

machine.output (somente leitura)

O gerenciador da saída para a sessão da emulação atual.

machine.memory (somente leitura)

O gerenciador da memória para a sessão da emulação atual.

machine.ioport (somente leitura)

O gerenciador da porta de E/S para a sessão da emulação atual.

machine.input (somente leitura)

O gerenciador da entrada para a sessão da emulação atual.

machine.natkeyboard (somente leitura)

Obtém o gerenciador do teclado natural, usado para controlar a entrada do teclado e do teclado numérico no sistema emulado.

machine.uiinput (somente leitura)

O gerenciador da entrada da IU para a sessão da emulação atual.

machine.render (somente leitura)

O gerenciador do renderizador para a sessão da emulação atual.

machine.debugger (somente leitura)

O gerenciador do depurador para a sessão da emulação atual ou nil se o depurador não estiver ativado.

machine.options (somente leitura)

As opções definidas pelo usuário para a sessão da emulação atual.

machine.samplerate (somente leitura)

A taxa de amostragem da saída do áudio em Hertz.

machine.paused (somente leitura)

Um booleano que indica se a emulação não está em execução no momento, geralmente porque a sessão foi pausada ou o sistema emulado não concluiu a inicialização.

machine.exit_pending (somente leitura)

Um booleano que indica se a sessão da emulação está programada para encerrar.

machine.hard_reset_pending (somente leitura)

Um booleano que indica se uma reinicialização forçada do sistema emulado está pendente.

machine.devices (somente leitura)

Um dispositivo enumerador que produz todos os dispositivos no sistema que está sendo emulado.

machine.palettes (somente leitura)

Um dispositivo enumerador que produz todos os dispositivos paleta no sistema que está sendo emulado.

machine.screens (somente leitura)

Um dispositivo enumerador que produz todos os dispositivos tela no sistema que está sendo emulado.

machine.cassettes (somente leitura)

Um dispositivo enumerador que produz todos os dispositivos da imagem em fita cassete no sistema que está sendo emulado.

machine.images (somente leitura)

dispositivo enumerador que produz toda a interface para os dispositivos de imagem no sistema que está sendo emulado.

machine.slots (somente leitura)

dispositivo enumerador que produz toda a dispositivos slot no sistema que está sendo emulado.

O gerenciador de vídeo

Encapsula a classe video_manager do MAME que é responsável por coordenar a exibição do vídeo que está sendo emulado, a aceleração da velocidade e da leitura das entradas do host.

Instanciação

manager.machine.video

Obtém o gerenciador do vídeo para a sessão da emulação atual.

Métodos

video:frame_update()

Atualiza as telas emuladas, lê as entradas do host e atualiza a saída de vídeo.

video:snapshot()

Salva os arquivos da captura da tela de acordo com a configuração atual. Caso o MAME esteja configurado para obter as capturas da tela emulada de forma nativa, a captura da tela que será salvo será de todas as telas que estiverem visíveis numa janela ou da tela do host com a configuração da exibição atual. Caso o MAME esteja configurado para obter as capturas da tela emulada de forma nativa, ou seja, o sistema não tiver uma tela emulada, uma captura da tela será salva usando a visualização selecionada no momento.

video:begin_recording([nome_do_arquivo], [formato])

Interrompe todas as gravações de vídeo em andamento e começa a gravar as telas emuladas que estão visíveis ou a exibição do captura da tela atual, dependendo se o MAME está configurado para obter as capturas nativas da tela emulada. Caso o nome do arquivo não seja informado, a configuração do nome do arquivo da captura da tela será usada. Caso o nome do arquivo seja um caminho relativo, ele será interpretado em relação ao primeiro diretório da configuração da captura da tela. Caso o formato seja informado ele deve ser avi ou mng. Se não for informado, a predefinição é AVI.

video:end_recording()

Interrompe qualquer gravação de vídeo em andamento.

video:snapshot_size()

Retorna a largura e a altura em pixels das capturas da tela criados com a configuração atual do destino e o estado da tela emulada. Isso pode ser configurado de forma explicita pelo usuário, calculado com base na visualização da captura selecionada e na resolução de quaisquer telas visíveis e que estejam sendo emuladas.

video:snapshot_pixels()

Retorna os pixels de uma captura criado usando a configuração do destino da captura atual em inteiros com 32 bits e compactados numa string binária com ordem Endian do host. Os pixels são organizados em ordem maior da linha, da esquerda para a direita e de cima para baixo. Os valores do pixel são cores no formato RGB compactadas em inteiros com 32 bits.

Propriedades

video.speed_factor (somente leitura)

Ajuste de velocidade da emulação configurada em escala de mil (ou seja, a proporção para a velocidade normal multiplicada por 1.000).

video.throttled (leitura e escrita)

Um booleano que indica se o MAME deve esperar antes das atualizações do vídeo para evitar a execução mais rápida do que a velocidade desejada.

video.throttle_rate (leitura e escrita)

A velocidade de emulação desejada como uma proporção da velocidade total ajustada através do fator de velocidade (ou seja, 1 é a velocidade normal ajustada pelo fator de velocidade, números maiores são mais rápidos e números menores são mais lentos).

video.frameskip (leitura e escrita)

A quantidade dos quadros emulados do vídeo para serem ignorados a cada doze ou -1 para ajustar automaticamente a quantidade de quadros para ignorar visando para manter a velocidade da emulação desejada.

video.speed_percent (somente leitura)

A velocidade emulada atualmente em porcentagem da velocidade total ajustada pelo fator da velocidade.

video.effective_frameskip (somente leitura)

A quantidade dos doze quadros emulados que são ignorados.

video.skip_this_frame (somente leitura)

Um booleano que indica se o gerenciador do vídeo vai ignorar as telas emuladas para o quadro atual.

video.snap_native (somente leitura)

Um booleano que indica se o gerenciador do vídeo fará capturas nativa da tela emulada. Além da definição da configuração relevante, o sistema emulado deve ter pelo menos uma tela que esteja sendo emulada.

video.is_recording (somente leitura)

Um booleano que indica se alguma gravação de vídeo está em andamento.

video.snapshot_target (somente leitura)

Um alvo do renderizador usado para produzir as capturas da tela e para as gravações de vídeo.

O gerenciador de áudio

Encapsula a classe sound_manager do MAME que gerencia o gráfico do fluxo do áudio emulado e coordena a sua saída.

Instanciação

manager.machine.sound

Obtém o gerenciador do áudio para a sessão da emulação atual.

Métodos

sound:start_recording([nome_do_arquivo])

Inicia a gravação num arquivo WAV. Não tem efeito se estiver gravando. Caso o nome do arquivo não seja informado usa o nome do arquivo WAV configurado (da linha de comando ou do arquivo INI) ou não tem efeito se nenhum nome do arquivo WAV estiver configurado. Retorna true se a gravação foi iniciada ou false se a gravação já estiver em andamento, a abertura do arquivo gerado falhou ou nenhum nome para o arquivo foi informado ou foi configurado.

sound:stop_recording()

Interrompe a gravação e fecha o arquivo se estiver um arquivo WAV estiver sendo gravado.

sound:get_samples()

Retorna o conteúdo atual do buffer da amostra gerada como uma string binária. As amostras são inteiros com 16 bits na ordem dos bytes do host. As amostras dos canais estéreo esquerdo e direito são intercaladas.

Propriedades

sound.muted (somente leitura)

Um booleano que indica se a saída do áudio está silenciada por algum motivo.

sound.ui_mute (leitura e escrita)

Um booleano que indica se a saída do áudio está silenciada a pedido do usuário.

sound.debugger_mute (leitura e escrita)

Um booleano que indica se a saída do áudio está silenciada a pedido do depurador.

sound.system_mute (leitura e escrita)

Um booleano que indica se a saída do áudio foi silenciada a pedido do sistema que está sendo emulado.

sound.attenuation (leitura e escrita)

A atenuação do volume da saída em decibéis. Geralmente deve ser um número inteiro negativo ou zero.

sound.recording (somente leitura)

Um booleano que indica se a saída do áudio está sendo gravada num arquivo WAV.

O gerenciador da saída

Encapsula a classe output_manager do MAME que fornece acesso às saídas do sistema que podem ser usadas para arte interativa ou consumidas por programas externos.

Instanciação

manager.machine.output

Obtém o gerenciador da saída para a sessão da emulação atual.

Métodos

output:set_value(nome, valor)

Define o valor de saída informada. O valor deve ser um número inteiro. A saída será criada caso ainda não exista.

output:set_indexed_value(prefixo, índice, valor)

Acrescenta o índice (formatado como um inteiro decimal) ao prefixo e define o valor da saída correspondente. O valor deve ser um número inteiro. A saída será criada caso ainda não exista.

output:get_value(nome)

Retorna o valor da saída informada ou zero caso não exista.

output:get_indexed_value(prefixo, índice)

Anexa o índice (formatado como um inteiro decimal) ao prefixo e retorna o valor da saída correspondente ou zero caso não exista.

output:name_to_id(nome)

Obtém o ID com número inteiro exclusivo por sessão para a saída informada ou zero caso não exista.

output:id_to_name(id)

Obtém o nome da saída com o ID exclusivo por sessão informada ou nil caso não exista. Este método tem complexidade O(n), portanto, evite chamá-lo quando o desempenho for importante.

O gerenciador de parâmetros

Wraps MAME’s parameters_manager class, which provides a simple key-value store for metadata from system ROM definitions.

Instanciação

Encapsula a classe parameters_manager do MAME que fornece um armazenamento simples do valor da chave para os metadados das definições da ROM do sistema.

Métodos

parameters:lookup(tag)

Obtém o valor do parâmetro informado caso esteja definido ou uma string vazia se não estiver.

parameters:add(tag, valor)

Define o parâmetro informado caso não esteja. Não tem efeito se o parâmetro informado já estiver definido.

O gerenciador da IU

Encapsula a classe mame_ui_manager do MAME que lida com menus e as outras funcionalidades da interface do usuário.

Instanciação

manager.ui

Obtém o gerenciador da IU para a sessão atual.

Métodos

ui:get_char_width(ch)

Obtém a largura de um caractere Unicode como uma proporção da largura do contêiner da IU na fonte atualmente utilizada na altura configurada da linha da IU.

ui:get_string_width(str)

Obtém a largura de uma string como uma proporção da largura do contêiner da IU na fonte atualmente utilizada na altura configurada da linha da IU.

ui:set_aggressive_input_focus(ativa)

Em algumas plataformas isso controla se o MAME deve aceitar o foco da entrada em mais situações do que quando as suas janelas têm o foco da IU.

ui:get_general_input_setting(type, [jogador])

Obtém uma descrição da sequência da entrada configurada para o tipo da entrada indicada e o jogador adequado para usar nos prompts. O tipo da entrada é um valor enumerado. O número do jogador é um índice com base no número zero. Caso o número do jogador não seja informado, é assumido o valor zero.

Propriedades

ui.options (somente leitura)

As opções da interface para a sessão atual.

ui.line_height (somente leitura)

A altura configurada da linha de texto da interface como uma proporção da altura do contêiner da interface.

ui.menu_active (somente leitura)

Um booleano que indica se um elemento da interface interativa está atualmente ativa. Os exemplos incluem os menus e os controles deslizantes.

ui.ui_active (leitura e escrita)

Um booleano que indica se as entradas de controle da IU estão ativadas.

ui.single_step (leitura e escrita)

Um booleano que controla se o sistema emulado deve ser pausado automaticamente quando o próximo quadro for desenhado. Esta propriedade é redefinida automaticamente quando acontecer a pausa automática.

ui.show_fps (leitura e escrita)

Um booleano que controla se a velocidade atual da emulação e as configurações do salto de quadro devem ser exibidas.

ui.show_profiler (leitura e escrita)

Um booleano que controla se as estatísticas da criação do perfil devem ser exibidas.

Os metadados do driver do sistema

Fornece alguns metadados para um sistema que estiver sendo emulado.

Instanciação

emu.driver_find(nome)

Obtém os metadados do driver informado para o sistema com o nome abreviado ou nil caso o sistema não exista.

manager.machine.system

Obtém os metadados do driver para o sistema atual.

Propriedades

driver.name (somente leitura)

O nome abreviado do sistema, conforme usado na linha de comando, nos arquivos de configuração e ao pesquisar os recursos.

driver.description (somente leitura)

O nome completo da exibição do sistema.

driver.year (somente leitura)

O ano do lançamento do sistema. Pode conter pontos de interrogação caso não seja totalmente conhecido.

driver.manufacturer (somente leitura)

O fabricante, o desenvolvedor ou o distribuidor do sistema.

driver.parent (somente leitura)

O nome abreviado do sistema principal para fins de organização ou "0" se o sistema não venha de uma matriz.

driver.compatible_with (somente leitura)

O nome abreviado de um sistema onde este sistema seja compatível com o software ou nil caso o sistema não esteja listado como compatível com um outro sistema.

driver.source_file (somente leitura)

O arquivo de origem onde este driver do sistema estiver definido. O formato do caminho depende do conjunto das ferramentas onde o emulador foi compilado.

driver.rotation (somente leitura)

Uma string que indica a rotação aplicada a todas as telas no sistema depois que a orientação da tela informada na configuração do sistema seja aplicado. Será um dos "rot0", "rot90", "rot180" ou "rot270".

driver.not_working (somente leitura)

Um booleano que indica se o sistema foi marcado como não funcionando.

driver.supports_save (somente leitura)

Um booleano que indica se o sistema é compatível com salvamento de estado.

driver.no_cocktail (somente leitura)

Um booleano que indica se se não existe compatibilidade para a inversão da tela em modo coquetel.

driver.is_bios_root (somente leitura)

Um booleano que indica se se este sistema representa um sistema que roda programas a partir de uma mídia removível sem que a mídia esteja presente.

driver.requires_artwork (somente leitura)

Um booleano que indica se se o sistema requer a utilização de uma ilustração externa.

driver.unofficial (somente leitura)

Um booleano que indica se se esta é uma alteração oficial, porém uma alteração comum do usuário para o sistema.

driver.no_sound_hw (somente leitura)

Um booleano que indica se o sistema não possui nenhum hardware de saída de áudio.

driver.mechanical (somente leitura)

Um booleano que indica se o sistema depende de recursos mecânicos que não podem ser devidamente simulados.

driver.is_incomplete (somente leitura)

Um booleano que indica se o sistema é um protótipo com funcionalidades incompletas.

Plug-in Lua

Fornece uma descrição de um plug-in Lua que esteja disponível.

Instanciação

manager.plugins[nome]

Obtém a descrição do plug-in Lua com o nome informado ou nil caso o plug-in não esteja disponível.

Propriedades

plugin.name (somente leitura)

O nome abreviado do plug-in usado na configuração e durante o acesso.

plugin.description (somente leitura)

Exibe o nome do plug-in.

plugin.type (somente leitura)

O tipo do plug-in. Pode ser "plugin" para os plug-ins que podem ser carregados pelo usuário ou "library" para as bibliotecas que fornecem funcionalidades comum aos diferentes plug-ins.

plugin.directory (somente leitura)

O caminho para o diretório que contém os arquivos de plug-in.

plugin.start (somente leitura)

Um booleano que indica se o plug-in está ativado.