Player configuration

Imagine you have a song that doesn’t use 100% of the AT 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: “Generate a configuration source for players”.

If activated, a source file will be generated along your music. It will have the same name, post-fixed 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: AT 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 also 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, AKG and AKM 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 (AKG, AKY, AKM plus Sound Effects) for Z80. What is missing, for now, are the specialized ones (AKY for Turbosound or PlayCity, AKY stabilized). 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 voilà!

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 :).

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 AKM 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.