There are a number of compiletime flags and variables which control some statically configurable aspects of AGT. Changing these generally requires a recompilation of AGT's sourcefiles (i.e. make clean) as feature availability and code generation will be affected.

Some of these are temporarily named and will soon adopt the AGT_CONFIG_ prefix

configuration:

AGT_CONFIG_WORLD_XMAJOR AGT_CONFIG_WORLD_YMAJOR

Specify dominant axis of game world as X or Y. This helps the engine optimise some internal processes.

e.g. A horizontal scroller would specify XMAJOR, vertical scroller would specify YMAJOR. A multiway scroller can use either if there is no dominant axis. If you plan a mixture of levels then choose the axis which will help optimise the level(s) with the busiest entity traffic.

AGT_CONFIG_VISTRIGGER

Enable support for VISTRIGGER entities. These are entities marked with EntityFlag_VISTRIG instead of EntityFlag_TICKED. They will not be ticked until the viewport approaches their position on the map, at which point they are promoted from VISTRIG to TICKED status and 'wake up'. This is helpful where many objects may be spawned into the world during level load (e.g. via XML exported from a game level editor), but in a low-cost sleeping state until encountered during play.

There is a tiny cost associated with having this feature enabled (at least, when not trying to spawn entities at the start of a level) so it defaults off.

AGT_CONFIG_ENTITYLAYERS=<NUMLAYERS>

Enable layer support for entities, providing NUMLAYERS draw priorities (independent sorting layers). This defaults off, and incurs a tiny penalty when enabled. Values of 2 upwards will enable the feature.

If you need sorted drawing for correct visuals then turn this on - the small saving which can be seen from disabling it is not worth giving up important functionality!

Entity drawing order can then be managed by setting the entity [drawlayer] field at any time - in the entity dictionary or within the tick functions.

Don't assign an entity [drawlayer] value >= the defined NUMLAYERS value as this would be undefined behaviour.

AGT_CONFIG_DYNAMIC_TICKPRIO

Enable support for dynamic tick priority. i.e. objects which can change their tick priority after spawning. This incurs a (small) extra cost and usually not required, so it must be specified if needed.

If you need an entity to always tick before (or after) all the others, this is how to manage it. It can be useful if your viewport has a tick function of its own, or for more complex AI which has dependencies between entities, especially if the tick ordering needs to change at runtime.

AGT_ENTITY_USER_EXTENSION

This allows the entity structure entity_t to be extended with user fields, effective across all entities. All of the existing samples use the standard set of fields available, in some cases overloading unused fields for other purposes. This can only be taken so far if the game AI grows complex, so extending with custom fields is the way to go.

Some changes are needed in the game code to make use of this - to define the new fields in a extended structure. This will be documented elsewhere and in a provided sample.

AGT_CONFIG_SYS_GUARDX AGT_CONFIG_SYS_GUARDY

These define the hidden guardband area used by the drawing system. If not set, it will default to X=32, Y=32. This is fine for most situations and perfect when all sprites are <= 32x32 pixels in size.

GUARDX should be configured globally and use the same value across all playfields, because it affects the code generated for some of the more advanced features such as tile animation and EMX sprite drawing. It is possible to set it differently per playfield arena (it is an optional argument) but it could cause problems with some features. If h-scrolling is active, it cannot be set lower than a value of 32 because the scrolling system enforces a hidden region for scrolling purposes.

GUARDY can be configured globally but it can also be set differently per playfield arena. This does not cause any issues. Some sprites have physical y-clipping and do not need a y-guardband (EMS, SLAB or EMX without '-nc' noclip flag) but others (EMH, EMX -nc) can't be clipped and need the guard area otherwise they turn invisible on contact with the guard/screen edge.

For h-scroll parallax splits, the GUARDY value should be configured to 0 for each split sub-arena, so physical clipping will be enforced at the split. The game must then use EMS or EMX when drawing sprites efficiently across those splits. Using a y-guardband on splits will work but is very inefficient as the sprite will be re-drawing to hidden areas above and below each split as they are crossed, wasting a lot of cycles.

AGT_CONFIG_PACKER_ANY AGT_CONFIG_PACKER_???

Enable support for packed assets. Choose 'ANY' to begin with, to save trouble. When optimising the memory use of your game towards the end, remove 'ANY' and enable just the packing formats you need. This will save a little space from unused code.

AGT_CONFIG_QUIET

Silence all printf messages. Typically used when the game is 100% ready - not so great while debugging.

AGT_CONFIG_NO_WRAPCRC

Skip the CRC check of wrapped assets as they are loaded from disk. This CRC mostly checks for disk reading errors and can be helpful while developing if the hardware or debugging environment has unreliable transfers. Disabling the CRC with this defined saves a small amount of loading time.

AGT_CONFIG_NO_UNWRAPCRC

Skip the CRC check when loading wrapped assets after unwrapping / unpacking to memory. This mainly checks for faults in the decompression (packer/unpacker) and can be used to save a little loading time when everything is known to be working reliably before releasing your project.

AGT_CONFIG_SYS_EMS_XCLIP

This enables support for physical x-clipping, but only on the EntityDraw_EMSPRQ sprite path and only for sprites <= 32 pixels wide. Because the GUARDX guardband is likely active already and generally >=32 pixels wide (the minimum for h-scroll configurations), physical x-clipping is generally not adding value except to make the sprite drawing slightly more complicated - on the fastest sprite path.

There may be some situations where some very tall, narrow sprites are often crossing the left/right screen edge and there may be some saving from enabling this feature but that would be considered a very special case.

AGT_CONFIG_SYS_EMXQ_PREFER_YCLIP

EMX sprites are extremely fast but cannot be clipped and large EMX sprites require a large guardband allow them to cross the screen edge.

EMS sprites can be clipped and use much less memory, but are slower to draw.

EMX sprites by default will embed an EMS-formatted copy of the same data to allow y-clipping at the top/bottom screen edge. EMX automatically switches to EMS mode when contacting the screen edge. This is mainly because a y-guardband was only recently introduced and there was no other way to clip EMX sprites.

This 'PREFER_YCLIP' flag controls the decision point for EMX to switch to EMS and perform physical y-clipping. By default, yclip will occur when the EMX touches the guardband edge - this means it may be partly or fully offscreen when it tries to switch. This is normally preferred because the drawing cost can only go down, not up, when clipping switches on since much of the sprite will stop drawing.

Enabling 'PREFER_YCLIP' will cause EMX to switch to clipping mode when the sprite touches the visible screen edge, ignoring the guardband. This begins clipping early, but can cause drawing cost to spike up, because EMS is slower to draw than EMX and the whole sprite will be visible when the switch occurs.

This flag only has effect on the EntityDraw_EMXSPRQ drawing path.

Embedding of EMS in EMX sprites can be disabled using the -nc (noclip) flag in the sprite asset cutting commands. This saves some memory but makes EMX depend on GUARDY. Normally, this is what you will want to do because memory pressure is mainly coming from the EMX itself, not from the guardband memory.

debugging:

AGT_CONFIG_SAFETY_CHECKS

Turn on entity drawing & management safety checks. This is recommended while developing projects.

Out-of-bounds animation frames will halt with a console error providing information on the faulting entity.

Faulty entity management e.g. removing objects more than once, removing inactive objects or spawning objects from removed/inactive objects will report appropriate errors or warnings.

Output goes to console/log. As with the other debugging features, ensure the build configuration is not set to 'release' or the log output may be suppressed. Prefer 'testing' for optimised diagnostic builds.

AGT_CONFIG_ENTITY_TRACKING

Enables tracking of all significant entity events including spawns, removals and types of objects involved.

Output goes to console/log. As with the other debugging features, ensure the build configuration is not set to 'release' or the log output may be suppressed. Prefer 'testing' for optimised diagnostic builds.

AGT_CONFIG_ENTITY_HISTOGRAM

Assuming AGT_CONFIG_ENTITY_TRACKING is also enabled, this option additionally tracks counts for each type of entity and reports the counts on every spawn/removal event. This floods the log with prints but can be useful to track leaking entities or faulty call ordering problems.

AGT_CONFIG_DEBUGDRAW

Enables debug drawing primitive which renders all entities as filled rectangles instead of their configured EntityDraw type. Once enabled, the feature can be toggled at runtime with g_debugdraw=0/1

AGT_CONFIG_DEBUG_CONSOLE

Enables the AGT debug console. This directs all printf and error message events to a console window in the lower screen border. The console can be shown by holding TAB, or toggled with LSHIFT+TAB.

Note: This currently works only in overscan (240 lines) mode, which is the default mode. Support for 200 lines + console will be added later.

AGT_CONFIG_STEEM_DEBUG

Directs all printf and error messages to the STEEM virtual log for convenient debugging.

WARNING: This causes a bus error on anything except the STEEM emulator. Not compatible with real hardware.

HATARI_NF_PRINTF

Directs all printf and error messages to Hatari's NATFEATS virtual log for convenient debugging. Must start Hatari with --natfeats=yes and also ensure the Hatari console/debug window is open.

USE_MEMTRACE

Prints all memory activity and commit level as a result of asset loading or using new/delete or malloc/free.

TIMING_RASTERS TIMING_RASTERS_MAIN

Turn on raster timing for system and mainloop sections (work in progress!)

AGT_CONFIG_PROFILER

Enables the built-in sampling profiler, which records CPU load for the most significant engine components plus any user-defined regions to be profiled in the game code.

This requires some definitions to be added to the game code in order to link properly. See Profiler for details on use.

extras:

ENABLE_AGT_AUDIO

Enables the midi-based YM player which uses AGT's custom BMZ format, requiring the agtym midi conversion tool. This is already functional for music but remains work-in-progress. Still lacks SFX support.

AGT_CONFIG_AUDIO_200HZ

Configures the YM player to use 200Hz replay instead of the default 50Hz. Improves some FX capabilities but quite expensive.