Outline:

IMPORTANT: The Makefile structure has recently been updated, simplifying each project Makefile while adding some new features. Most of the build mechanics now live in 'makedefs.', 'makerules.' and associated bash scripts.

The Makefile used by each sample project may include some additional rules for collating data such as music, sample WAVs etc. These extra rules are project-specific. The tutorials will tend not to need them.

Common Makefile configuration:

Each project must point at AGT's root directory (typically agtools/) in order to orient for scripting and to locate binaries. It also allows a project to track a specific working version of AGT while you experiment with updates. For most of the existing samples, which live within agtools/, the setting will tend to look like this:

AGTROOT=../..

Give the project a name. This is mainly used during disk imaging / virtual disk mounting, not so much by the build process itself.

PROJECT := abreed

Select a build configuration: release, testing, debug

release is fully optimized, without self-checks or unnecessary reporting testing is optimized but with self-checks and additional reporting enabled debug is unoptimized with additional reporting and self-checks enabled

BUILD_CFG := testing

Note: If you are trying to debug via the log/console and not seeing your messages, ensure you have configured to 'testing' build mode, and that either Steem or Hatari logging features are also enabled in the Makefile and emulator side (especially for Hatari, which needs --natfeats=yes). The builtin AGT console will also record prints, but will only work if it is enabled in the Makefile.

USE_HATARI_NATFEATS = no (yes)

Enabling this will pipe printf messages, warnings, errors etc. to the Hatari console. Note that they reach the Hatari console only. You will no longer see messages from the TOS console. However you will now see messages via Hatari which don't make it past initial loading phase (after the screen HW is claimed). AGT normally silences the TOS console while the game is running.

This is a very useful setting when developing under Hatari since no prints will be missed.

It requires enabling also at the Hatari side with this switch: --natfeats=yes

Note there is a COMPILERDEFS switch to enable something similar for STEEM Boiler (emulator debugger, with console log). However it has the added downside that it communicates via a HW register that causes real machines to crash if left enabled. Keep this in mind! -DAGT_CONFIG_STEEM_DEBUG

POST_UPX_PACKER = no

Optionally pack final executables with UPX. Note that only 'release' builds will use this setting.

PRODUCT_DISK1 := ./disk1
PRODUCT_DISK2 := ./disk2

For each distinct 'disk image', this specifies a working directory to build the filesystem for that image. This is basically where a lean version of your game/demo is placed after a build. It is normally possible to mount e.g. 'disk1' folder in an emulator and just boot the directory (it will contain a auto folder).

Actual disk images (.st, .msa etc.) can be made from these directories if required.

Most of the provided samples produce only disk1 but a few will produce 2 disks (demos/abreed produces a 2nd disk with a split-screen version of the same demo)

IMAGES := ./images

Location to output disk images, if relevant.

COMPILERDEFS +=

This is where AGT features may be build-time configured. Note that AGT is now built locally per project, so these settings should no longer cause conflicts with multiple active projects.

Note that COMPILERDEFS is split into two sections. The first configures release features, the second configures mainly diagnostic, debugging and reporting related features and should normally all be disabled in a final build.

Every project should at least select AGT_CONFIG_WORLD_XMAJOR or AGT_CONFIG_WORLD_YMAJOR in COMPILERDEFS to get valid builds of AGT. More on the meaning of individual settings at the end.

If your project has additional sourcefiles, add them here.

PROJECT_SRC_LIST =

IMPORTANT: the primary/main sourcefile should always be named ${PROJECT}.cpp just as the binary should be named ${PROJECT}.prg. The build rules will look for the ?.cpp to match the ?.prg target specified. So only addtional sourcefiles should be added to this list - don't include the primary one!

If your project has local includes, add them here.

PROJECT_INC_LIST =

You may optionally add a list of 'common' art/audio assets here, if you wish the generation of assets to be automatically triggered by art changes. If you prefer to run the generate scripts manually, you can leave this blank.

COM_SRC = source_assets
SOURCE_ASSETS_COMMON = ${COM_SRC}/mymap.png

Additionally, if you have level/stage specific assets being managed separately from common assets, you can define those similarly like so:

S1_SRC = source_assets/stage1
SOURCE_ASSETS_S1 = ${S1_SRC}/lev1map.png

Actual runtime assets (the files output from the assets_??.sh build scripts and to be loaded by your game) should always be added to this list. This is not optional. If you miss an asset, that file won't make it to the final image.

ASSETS_COMMON = $(ASSETS)/cursor.emx

Likewise, for level-specific assets, if they are being managed as separate groups:

ASSETS_S1 = $(ASSETS)/lev1map.ccm

Last, specify bootable binary and assets which map to each specific disk image.

DISK1_BINARY = $(BUILD_DIR)/game.prg
DISK1_ASSETS = $(ASSETS_COMMON) $(ASSETS_S1) $(ASSETS_S2)

DISK2_BINARY =
DISK2_ASSETS = $(ASSETS_S3) $(ASSETS_S4) $(ASSETS_S5) $(ASSETS_S6)

In the above case, all common/shared assets plus two game levels are being mapped to disk1. Remaining levels would go on disk2. It is straightforward to modify the Makefile to support additional disks.

caution:

If you're not used to makefiles, perhaps coming from a Devpac/68k universe, be aware that make is super strict about things like whitespace or newlines in the wrong place. If your makefile starts reporting obscure errors without any meaningful edits, check for trailing whitespace or accidental blank lines between important items. Keep regular backups of recent working versions. Make sure you are not accidentally converting linefeeds to DOS CRLF format also (check your Git config which may try to do this automatically e.g. if you see this its probably bad: [core] autocrlf=true).

AGT buildtime configuration

# playfield & entity config.

AGT_CONFIG_WORLD_XMAJOR     : world is primarily horizontal-scrolling
AGT_CONFIG_WORLD_YMAJOR     : world is primarily vertical-scrolling
AGT_CONFIG_VISTRIGGER       : entities can be pre-spawned into the level early and activated from sleep on entering viewport
AGT_CONFIG_DYNAMIC_TICKPRIO : entities can be given a tick priority/ordering, at some extra cost
AGT_CONFIG_ENTITY_LAYERS    : configure multiple drawing layers (draw priority)
AGT_ENTITY_USER_EXTENSION   : extend entity struct with user fields
AGT_CONFIG_SYS_GUARDX       : user configurable guardband for culling of very large sprites

# notes:
# - if in doubt, prefer XMAJOR
# - failing to specify one or other XMAJOR/YMAJOR will cause a build error

# packer config. can be used to save a little space.

AGT_CONFIG_PACKER_ANY       : enable all/any decompressors for asset loading
AGT_CONFIG_PACKER_LZ77      : enable lz77 for asset loading
AGT_CONFIG_PACKER_LZSA      : enable lzsa-1/lzsa-2 for asset loading
AGT_CONFIG_PACKER_PKE2      : enable pack2e/nrv2e for asset loading
AGT_CONFIG_PACKER_ARJ4      : enable arjbeta -m4 for asset loading
AGT_CONFIG_PACKER_ARJ7      : enable arjbeta -m7 for asset loading

# notes:
# - trying to load asset using a non-configured packer will log error to console
# - CRC (wrapped raw with added crc) method is always enabled

# debugging config.

TIMING_RASTERS              : enable timing rasters in engine
TIMING_RASTERS_MAIN         : enable timing rasters in local project 
USE_MEMTRACE                : print verbose memory allocation activity
AGT_CONFIG_QUIET            : silence printfs
AGT_CONFIG_PRINT_PLAYFIELD_METRICS : print internal playfield config, allocations
AGT_CONFIG_SAFETY_CHECKS    : internal safety checks to catch bad animation frames, entity events etc.
AGT_CONFIG_ENTITY_TRACKING  : track entity lifespans
AGT_CONFIG_ENTITY_HISTOGRAM : track entity activity (lists most abundant/costly entities)
AGT_CONFIG_DEBUGDRAW        : can draw entities are filled rectangles
AGT_CONFIG_DEBUG_OCCLUSION  : draws occlusion map activity into an overlaid framebuffer for debugging
AGT_DISABLE_DISPLAYSERVICE  : run game without claiming the display
AGT_CONFIG_STEEM_DEBUG      : output printfs to STEEM Boiler message log (note: crashes real HW!)
AGT_CONFIG_DEBUG_CONSOLE    : enable AGT debug console (occupies lower border, can be tabbed to fullscreen)
AGT_CONFIG_PROFILER         : enable AGT internal sampling profiler (needs separate docs)

# extras.

ENABLE_AGT_AUDIO            : enable audio / music player (for playing .bmu/.bmz files with sfx)
AGT_CONFIG_AUDIO_200HZ      : run audio system at 200hz vs 50hz (costly)