This is available since alpha4. It is optional! If you don't want to bother with it, don't! At your loss :).

Imagine you have a song that doesn't use 100% of the AT2 features. Do you think it is fair to use a player which waste memory (and probably CPU) to manage these anyway? Sure, you could delve into the source and remove these parts of code by yourself. But it's tedious, error-prone, maybe you don't know anything about players, and most of all, you don't have time to do it properly, you have a production to finish!

Well the good news is that Player Configurations will do the job for you.

An option appears when exporting a song or sound effects: "export player configuration source". If activated, a source file will be generated along your music. It will have the same name, postfixed with the name "_playerconfig". If you open the file, it will look like this:

PLY_CFG_ConfigurationIsPresent = 1
PLY_CFG_UseSpeedTracks = 1
PLY_CFG_UseEventTracks = 1
PLY_CFG_UseTranspositions = 1
PLY_CFG_UseHardwareSounds = 1
PLY_CFG_UseEffects = 1
PLY_CFG_SoftOnly = 1
PLY_CFG_SoftOnly_Noise = 1
PLY_CFG_SoftOnly_ForcedSoftwarePeriod = 1
...

What is that? Very simple: AT2 has analyzed your song and has generated all these flags to indicate the player (whatever it is) that, Speed Tracks are used, so are Event Tracks, and so on.

The player might check these flags and assemble parts of its code or not according to these flags! So it will take less memory, less instructions to execute, which can lead to substantial savings in CPU.

Why might? Because, depending on the export format, these flags may not be relevant to the player. For example, the AKY player, being a "streamed" player, does not care about technicalities such as "use forced software period in Software sound". However, Lightweight or AKG players will find these very useful information, as it means one branch of code will never be executed, so the whole test about the "forced software period" and its subsequent code will not be compiled.

How to use it? Very simple. As it is done in the testers, simply include the Player Configuration file(s) BEFORE the player itself is assembled. This is important to do it before, because the player checks the presence of these flags at its beginning. Example:

org #1000
...
include "MySong_playerconfiguration.asm"    ;Do that BEFORE including the player!
include "PlayerAky_CPC.asm"
include "MySong.asm"

Technical note: the players test the flag presence, not the flag values.

Can all the players use these Player Configuration files?

The main ones are (AKY, AKG, Lightweight, plus Sound Effects), for Z80. What is missing, for now, are the specialized ones (AKY for Turbosound or PlayCity, AKY stabilized, AKY accurate). Please tell me if this is needed, and I will do it.

I have three songs, and one player... How to handle this?

Simply include the three Player Configuration files one after the other BEFORE the player. The flags will stack up! Example:

include "FirstLevelSong_playerconfiguration.asm"
include "SecondLevelSong_playerconfiguration.asm"
include "GameOverSong_playerconfiguration.asm"

include "PlayerAky_CPC.asm"

include "FirstLevelSong.asm"
include "SecondLevelSong.asm"
include "GameOverSong.asm"

Note: you should use one song and three subsongs instead of having three songs. You can share their instruments/arpeggios/pitchs and save a lot of memory!

I have sound effects, does it work too?

I got you covered. Simply export a Player Configuration for them too, include it besides the Player Configuration of the song, BEFORE the player, and voila!

This is too complicated for me! I don't care about optimizations and all that! Can I ignore all this?

Yes! If you look at the beginning of the code of the player, you will see this:

IFNDEF PLY_CFG_ConfigurationIsPresent
      PLY_CFG_UseHardwareSounds = 1
      PLY_CFG_UseRetrig = 1
      ....
ENDIF

This basically means that if the "player configuration" is not there (because Player Configurations have not been added, because you don't care about these), flags will be automatically set. As a consequence, the full player is compiled. But don't complain if it takes too much memory or CPU :).

This also means that this feature does not break existing code!

How much will I gain?

It depends on the player and on your song.

You won't save much with AKY, since the code is quite simple and has not many branches. You could save a hundred of bytes, a few dozen of CPU cycles.

However, the Lightweight and the AKG especially will gain a lot from Player Configurations! You can save up to one and a half kilobyte on the player, and a few scanlines of CPU!

So don't hesitate, use this feature and don't go back.