7800 Pokey Engine

[+mksmith]

7800 Pokey Engine

Welcome to the 7800 pokey engine for music and sound effects playback on the Atari 7800 Console. This engine was initially developed (based on the disassembly and reverse engineering of Ms. Pac-man by Atari) by Perry Thuente (tep392) and Bob DeCrescenzo (pacmanplus) for the purpose of providing pokey sound playback for the Pac-man Collection. The engine has since been enhanced and is now also being used for other homebrew titles such as Millie & Molly 7800 (Matthew Smith), Popeye (Darryl Guenther) and Danger Zone (Lewis Hill) thanks to the awesome music abilities of Bobby Clark.

 

The 7800 pokey engine has been kindly open-sourced by the contributors and is freely available to the AtariAge community for use within any project. 

 

The source is currently maintained by Matthew Smith (mksmith) and is available to download from Github.

 

Contributors
The following people have contributed to developing the pokey engine:

• Perry Thuente @tep392
• Bob DeCrescenzo @PacManPlus
• Bobby Clark @Synthpopalooza
• Mike Saarna @RevEng
• Matthew Smith @mksmith
• Paul Lay @playsoft

 

Additional Testing

The following people have contributed to testing the pokey engine:

• Robert Tuccitto @Trebor

 

Titles using the pokey engine
The following titles are using variants of the pokey engine:

• Pac-man Collection (pacmanplus, tep392)
• Millie & Molly 7800, Arkanoid, Robots Rumble (mksmith)
• Popeye (darryl1970)
• Danger Zone, EXO, Keystone Kapers, ARTI (muddyfunster)

 

Music development

Bobby Clark (synthpopalooza) is the first and foremost expert in developing music and sound effects using this engine and has produced some outstanding compositions.  I'm sure he would be happy to help you if you ask!

 

Compiling for the Concerto Beta
When compiling builds for use on the Concerto beta there are a couple of things you need to be aware of:

• Enable the SKIPINITFORCONCERTO flag in pokeysound.asm
• 144k ROM is the best supported ROM size and should work without additional change
• 128K+RAM ROM will work but the ROM header will need to be manually changed to remove the pokey @ $450 flag
• 128K ROM does not produce any pokey sound

 

These notes will be updated as batari makes enhancements and changes to the Concerto firmware.

 

Changelog

v1.05 (18 Aug 2022)

• v1.05 - updated pokey detection routine from 7800basic 0.20 (reveng, mksmith)
• v1.04 - updated information for customizing a build for the concerto beta
• v1.03 - re-implemented CHANNLSKCTLS lookup (mksmith) 
• v1.02 - renamed SKIPCHECKFORPOKEY to SKIPINITFORCONCERTO and verified changes work (mksmith, trebor)
• v1.01 - updated SKIPCHECKFORPOKEY process to better handle $450 detection (playsoft)
• v1.00 - open sourced to Github (mksmith)
• v0.11 - added queue scheduling (playsoft) and SKIPCHECKFORPOKEY flag Concerto issue). Added RESETPOLYON and CHANNLRESETON table flags (mksmith)
• v0.10 - removed number of channels (not required) and added a tune-by-tune reset table (mksmith)
• v0.9  - removed SKCTL set and added ability to set number of channels to activate (mksmith)
• v0.8  - added MUTEMASKRESTFLG const so rest value can be customised (mksmith)
• v0.7  - re-implemented MUTEMASK change (reveng)
• v0.6  - fix 16-bit mode, SKCTL, or any mode requiring one channel be silenced and stops popping noises (sythnpopalooza) 
• v0.5  - 7800basic Pause Support (mksmith)
• v0.4  - 7800basic PAL Support (mksmith) [suggestion on how to implement by reveng]
• v0.3  - Reset poly support (sythnpopalooza)
• v0.2  - Added PLAYPOKEYSFX enhancements, STOPPOKEYSFX (mksmith)
• v0.1  - Initial version provided by pacmanplus and sythnpopalooza

 

Using the pokey engine in 7800basic

The engine itself is reasonably straight forward to integrate into 7800basic and there is a detailed example for how to properly setup and configure your game to use it.  Saying that it can be tricky at the beginning as you will need to determine the required features to be activated and also configure and locate the music itself potentially across various banks.  The basic process is as follows:

• copy file pokeysound.asm into the base root folder of your game. 7800basic will automagically replace the base file in 7800basic during compilation.
• inline pokeyconfig.asm into your game source (this should be the end of the last shared bank so it can be accessed at all times)
• inline your musicxxx.asm file(s) into your game source. There can be one of more of these spread across multiple banks depending on how you game is structured but in reality as with bank sharing the tune data MUST be available to be currently active bank.

 

Other changes to your source
The following changes are required to be made to your 7800basic source:

 

1. Insert the following vars:

 dim POKEYADR = $450   ;$450 (modern homebrew) or $4000
 dim TUNEAREA = $2200  ;range $2200-$2246 (46 bytes)            
 dim SOUNDZP = y.z     ;all pointers must be located in zeropage

Note: The TUNEAREA location or SOUNDZP vars can be changed to suit your requirements.

2. Include the following to service the player each frame (this should be in the last shared bank so it can be accessed at all times):

topscreenroutine
  rem call the pokey servicing routine
  asm
    jsr SERVICEPOKEYSFX
end
return

Examples

• example1.78b - basic implementation showing how to integrate the 7800 pokey engine into 7800basic including adding pokeyconfig and music data assembly files via the inline feature, calling and playing multiple different tunes and sound effects.

 

Additional notes

• tunes can be moved into RAM and played from there if required (example coming soon)
• an release for assembly users will be added soon

 

Need some help?

Contact Matthew Smith (mksmith) if need any assistance implementing this engine into your game.  

Edited February 4 by mksmith
Updated latest version notes and games utilizing the engine

[+mksmith]

A minor updated has been made to the SKIPCHECKFORPOKEY routine to better handle $450 detection (mainly for A7800) when building a Concerto beta specific build.  Thanks @playsoft ?

[+Muddyfunster]

@mksmith Thanks for continuing to work on this Matt (and thanks to the other folks who have contributed to it as well!) 

 

The POKEY functionality is fantastic, and the continued improvements (while mostly go over my head) are welcomed. If only there was a simple way for me to turn the notes into numbers

 

 

[Synthpopalooza]

By the way I almost have an 8-channel dual POKEY dragonfly update on this code. Just trying to get comfirmation that it works on real HW then I will share the code.

[Synthpopalooza]

This is kinda what I have so far ... the .a78 I got to compile from it didn't seem to work in the Dragonfly but I think it may be some kind of issue with the header.  Any of you fine gentlemen are welcome to look over the code and see if you can find any obvious errors, lol.

 

 

metroid-dblpokey.zip

[+mksmith]

Awesome Bobby! I'll probably get a chance to look over it tomorrow (basketball tournament on atm).

[+mksmith]

2 hours ago, Muddyfunster said:

@mksmith If only there was a simple way for me to turn the notes into numbers

Your right about that mate ?

 

[Synthpopalooza]

Take note:  This code doesn't have the latest changes to it, like MUTEMASK, etc. (it's from an older code) ... plus I have not yet sussed out how to work RESETPOLY with it, in that there are now two POKEYs to deal with.  First POKEY is placed at $440 and second at $450.

[Synthpopalooza]

2 hours ago, Muddyfunster said:

@mksmith Thanks for continuing to work on this Matt (and thanks to the other folks who have contributed to it as well!) 

 

The POKEY functionality is fantastic, and the continued improvements (while mostly go over my head) are welcomed. If only there was a simple way for me to turn the notes into numbers

 

 

There is of course my POKEY table which is elsewhere in the forum.  And it's still a work in progress, I may actually have to split it into several documents.

[SlidellMan]

This is a must for those who want POKEY support in their games. Matt, I salute you.

[+mksmith]

Thanks some on-cart testing from Robert @Trebor and additional information from Fred @batari we have some known conditions around compiling 7800basic builds for the Concerto (currently v0.95) firmware:

• Enable the SKIPINITFORCONCERTO flag in pokeysound.asm
• 144k ROM is the best supported ROM size and should work without additional change
• 128K+RAM ROM will work but the ROM header will need to be manually changed to remove the pokey @ $450 flag
• 128K ROM does not produce any pokey sound

[+mksmith]

Added the following changes (v1.03):

• re-implemented CHANNLSKCTLS lookup

This feature allows the use of the SKCTL two tone mode on a per tune basis by adding a lookup table.

[SlidellMan]

Will support for larger ROMs be possible?

[+mksmith]

1 hour ago, SlidellMan said:

Will support for larger ROMs be possible?

Any ROM size is supportable.  For our new cart options it really comes down to whether they support the ROM format at this point.

 

Music data can be located and played directly from shared banks (from ROM) or copied into RAM so it can be instigated from any bank as required.  For example Millie & Molly is a 128kRom with 8 banks.  Bank 1 stored all the music data for the 5 different in-game tunes and they are copied into RAM before a level is started - in my case playing of a level occurs in Bank 2 or 3 where they just wouldn't fit.  Other music is stored in banks 6 and 8 and played from there as specific Title, Level Complete and Game Complete screens are located. 

 

I need to add an example showing how copying into RAM works.