Som e música: SOUND, trackers e MegaROM

1. Dois níveis de controle

O CrossScript não usa a família MML (PLAY "T120 O4 ...") do BASIC clássico. Em vez disso, oferece dois caminhos que se complementam:

Comando	Nível	Para que serve
SOUND	Baixo	Efeitos: tiro, pulo, explosão, jingles curtos
PLAYMUSIC / STOPMUSIC / PAUSEMUSIC	Alto (player)	Trilha de fundo tocando sozinha, sincronizada com o VBLANK

Os dois escrevem nos mesmos canais PSG: um efeito pode ser sobrescrito no próximo tique musical.

2. SOUND — efeitos sonoros crus

SOUND registro, valor escreve diretamente num registro do PSG (AY-3-8910). É o comando para quem quer efeitos específicos: ruído branco de explosão, deslize de laser, click de menu.

O CrossScript também aceita formas nomeadas mais amigáveis:

• SOUND NOTE canal, nota, volume — toca uma nota no canal 0/1/2 (A/B/C). A nota vai de 0 a 95 (12 por oitava: 0 = dó da oitava 0, 48 = dó da oitava 4, 57 = lá 440 Hz); o volume vai de 0 a 15. As notas 0 a 11 são graves demais para se ouvir.
• SOUND NOISE período, volume — configura o ruído.
• SOUND MIX tons, ruídos — liga/desliga tons e ruídos por canal (registrador 7).
• SOUND ENV período, forma — configura o envelope de volume.
• SOUND REG r, v — escrita crua (equivalente ao SOUND clássico).
• SOUND OFF — silencia tudo.

Registros mais usados na forma SOUND REG:

Registro	Função
0, 1	Frequência canal A (LSB, MSB)
2, 3	Frequência canal B
4, 5	Frequência canal C
6	Frequência do ruído
7	Mixer (quais canais ligados)
8, 9, 10	Volume dos canais A, B, C

USES SCREEN 1, SOUND
SCREEN 1

SOUND REG 6, 15                ' ruído médio
SOUND REG 7, %00111000         ' habilita ruído nos 3 canais
SOUND REG 8, 16
SOUND REG 9, 16
SOUND REG 10, 16
DELAY 60
SOUND OFF

USES SCREEN 1, SOUND
SCREEN 1

DIM n AS BYTE
FOR n = 0 TO 11
  SOUND NOTE 0, 48 + n, 12    ' canal A, dó..si da oitava 4, volume 12
  DELAY 8
NEXT n
SOUND OFF

3. PLAYMUSIC — música VGM dentro do cartucho

O Music Importer (AT2) aceita arquivos .vgm e .vgz com escritas PSG (AY-3-8910). No Arkos Tracker 2, use File → Export → VGM — não AKM. A IDE converte a música em uma sequência RLE e gera o programa pronto para copiar; não há número de recurso musical.

1. Abra MÚSICA e selecione o VGM/VGZ.
2. Para músicas pequenas, mantenha Modo: Simples (32KB).
3. Copie o trecho e cole no script CSX. A música fica no bloco ASM, identificada por um rótulo, como MUSIC_DATA.
4. Use RUN para testar ou exporte a ROM.

PLAYMUSIC MUSIC_DATA inicia o player, mas não instala uma interrupção automaticamente. Você precisa chamar TICKMUSIC uma vez por quadro. O trecho do importador já usa ON VBLANK GOSUB para que a música acompanhe a interrupção de vídeo, independentemente da carga do jogo.

USES SCREEN 2, MUSIC, KEYBOARD
SCREEN 2 : CLS
PLAYMUSIC MUSIC_DATA
ON VBLANK GOSUB TOCAMUSICA
WHILE STRIG(0) = 0
  WAIT
WEND
STOPMUSIC
END

TOCAMUSICA:
  TICKMUSIC
RETURN

ASM
MUSIC_DATA:
        DW MUSIC_DATA_LOOP
MUSIC_DATA_LOOP:
        DB $07,$BE,$00,$AA,$01,$01,$08,$0C,$FE,$3B
        DB $08,$00,$FE,$1D,$FD
END ASM

Essa sequência curta toca uma nota e faz uma pausa antes de repetir. Para uma trilha completa, substitua o bloco pelo gerado no importador. PAUSEMUSIC alterna entre pausa e retomada; STOPMUSIC encerra e silencia os três canais PSG.

4. TICKMUSIC — um passo por quadro

Você também pode chamar TICKMUSIC no loop principal, logo após WAIT. Nesse caso, não registre também a chamada no VBLANK: duas chamadas por quadro aceleram a música.

USES SCREEN 2, MUSIC
SCREEN 2
PLAYMUSIC MUSIC_DATA
WHILE 1
  WAIT
  TICKMUSIC
WEND

ASM
MUSIC_DATA:
        DW MUSIC_DATA_LOOP
MUSIC_DATA_LOOP:
        DB $07,$BE,$00,$AA,$01,$01,$08,$0C,$FE,$3B,$FD
END ASM

O ritmo segue a frequência de vídeo: em NTSC são cerca de 60 passos por segundo; em PAL são 50. O player não adapta automaticamente uma música de 50 Hz para 60 Hz.

5. Módulos de tracker: .PT3 e .PRO

Além do VGM, o CrossScript toca dois formatos de tracker direto, sem conversão:

Formato	Tracker	Chip	Comandos
.PT3	Vortex Tracker II / ProTracker 3	PSG (todo MSX)	PLAYPT3 endereço, TICKPT3, STOPPT3
.PRO	Tyfoon Pro-Tracker	MSX-MUSIC (FM)	PLAYPRO endereço, TICKPRO, STOPPRO

Na janela de música da IDE, clique em Importar .PT3 / .PRO. A IDE reconhece o tipo do arquivo e monta o programa pronto. Escolha onde a música fica:

• No cartucho — os bytes da música entram no próprio programa. Bom para músicas pequenas.
• No disquete — o programa lê o arquivo com LOADFILE ao começar. Bom para músicas grandes ou para trocar de música sem recompilar.

Chame TICK… uma vez por quadro, logo depois do WAIT: assim a música anda a 60 passos por segundo.

USES SCREEN 0, PT3, KEYBOARD
DIM MUSADR AS WORD
SCREEN 0
ASM
        LD      HL, MUSICA_PT3
        LD      (@MUSADR), HL
END ASM
PLAYPT3 MUSADR
PRINT "Tocando... ESPACO para parar"
WHILE STRIG(0) = 0
  WAIT
  TICKPT3
WEND
STOPPT3
END

ASM
MUSICA_PT3:
        DB $00                      ; a IDE troca pelos bytes do .PT3
END ASM

MEMORY COM NAME "TOCAPRO"
USES SCREEN 0, DISK, PRO, KEYBOARD
DIM ST AS BYTE
SCREEN 0
LOADFILE "MUSICA.PRO", $9000, ST
IF ST <> 0 THEN
  PRINT "Musica nao encontrada"
  END
ENDIF
PLAYPRO $9000
PRINT "Tocando... ESPACO para parar"
WHILE STRIG(0) = 0
  WAIT
  TICKPRO
WEND
STOPPRO

Grave o programa como DSK e copie MUSICA.PRO para o mesmo disquete. Para um .PT3, troque PRO por PT3 nos comandos e no USES.

6. Música em MegaROM Mapper (ASCII8)

Para VGM/VGZ maiores, marque MegaROM Mapper (ASCII8) no importador. Acima de 9.830 bytes de RLE, essa opção é ativada e permanece obrigatória; o importador aceita até 49.152 bytes (48 KB) de música convertida. Músicas pequenas também podem usar Mapper por escolha sua.

O programa continua nos primeiros 32 KB; a música fica nos blocos seguintes, de 8 KB. A ROM final tem pelo menos 64 KB, crescendo em potências de dois conforme necessário. Isso não segmenta código, tiles ou sprites: o jogo e seu runtime ainda precisam caber nos primeiros 32 KB. Não acrescente MEMORY AUTO, MAPPER: essa diretiva geral não implementa essa separação; quem ativa a MegaROM musical é PLAYBANK com BANKDATA.

Comando	Uso
PLAYBANK	Reinicia a música dos blocos no início; sem parâmetro
TICKBANK	Avança um passo; chame uma vez por quadro
STOPBANK	Para e silencia os canais PSG
BANKLOOP deslocamento	Posição de repetição, em bytes a partir do primeiro BANKDATA
BANKDATA byte, ...	Bytes RLE da música, na ordem; fora de ASM

USES SCREEN 2, KEYBOARD
SCREEN 2 : CLS
PLAYBANK
ON VBLANK GOSUB TOCABLOCOS
WHILE STRIG(0) = 0
  WAIT
WEND
STOPBANK
END

TOCABLOCOS:
  TICKBANK
RETURN

BANKLOOP 0
BANKDATA $07,$BE,$00,$AA,$01,$01,$08,$0C,$FE,$3B
BANKDATA $08,$00,$FE,$1D,$FD

O importador gera essas linhas automaticamente, inclusive a posição correta do loop. Não transforme BANKDATA em DB: a música precisa ficar fora do bloco do programa. RUN carrega a ROM como ASCII8 automaticamente; ao exportar e abrir em outro emulador, selecione ASCII8 se a detecção automática não reconhecer o cartucho.

Esta opção é exclusiva do fluxo VGM/RLE em cartucho. Não há PAUSEBANK nesta etapa; STOPBANK seguido de PLAYBANK reinicia a música. PT3/PRO permanecem no cartucho normal ou no disquete. O botão Gravar .MUS continua gerando o arquivo para LOADFILE com o player normal, não uma MegaROM.

7. Regras práticas

• Uma música por player. Iniciar outra substitui a anterior.
• Não use PLAYMUSIC e PLAYBANK juntos: ambos escrevem no mesmo PSG.
• Efeitos SOUND disputam os mesmos canais da trilha; o próximo tique musical pode sobrescrevê-los.
• Chame STOPMUSIC, STOPBANK, STOPPT3 ou STOPPRO antes de sair.
• PLAY "..." (MML) não existe no CrossScript.

8. Resumo do capítulo

• SOUND controla efeitos PSG.
• PLAYMUSIC rótulo, TICKMUSIC, PAUSEMUSIC e STOPMUSIC usam a música dentro do programa ou carregada do disco.
• PLAYBANK, TICKBANK, STOPBANK, BANKLOOP e BANKDATA usam blocos de uma MegaROM ASCII8.
• PLAYPT3/PLAYPRO tocam módulos de tracker; cada player exige seu TICK por quadro.
• O importador gera o trecho pronto com a chamada de música no VBLANK; copiar e colar não substitui seu script automaticamente.