### Amiga "Hello world" CMake Build Configuration

Source: https://github.com/amigaports/ace/blob/main/docs/programming/hello_world.md

This CMakeLists.txt file configures the build process for the Amiga "Hello world" example. It sets up the project, specifies C standard and flags, includes ACE library, and handles executable creation for different Amiga compilers (Bartman/Bebbo) and build targets (ELF2HUNK).

```cmake
cmake_minimum_required(VERSION 3.14.0)
project(hello LANGUAGES C)

# Lowercase project name for binaries and packaging
string(TOLOWER ${PROJECT_NAME} PROJECT_NAME_LOWER)

if(NOT AMIGA)
	message(SEND_ERROR "This project only compiles for Amiga")
endif()

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DAMIGA -Wall -Wextra -fomit-frame-pointer")
file(GLOB_RECURSE SOURCES src/*.c)
file(GLOB_RECURSE HEADERS src/*.h)

include_directories(${PROJECT_SOURCE_DIR}/src)

# Debugging flag exposed via CMake specifically for your game code
if(GAME_DEBUG)
  set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DGAME_DEBUG")
endif()

# ACE
add_subdirectory(deps/ace ace)
include_directories(deps/ace/include)
# If you built standalone and installed ACE, use following instead:
# find_package(ace REQUIRED)
# include_directories(${ace_INCLUDE_DIRS})

# Force lower-case binary name for Linux etc.
set(TARGET_NAME ${PROJECT_NAME_LOWER})

if(ELF2HUNK)
  # Add elf2hunk step for Bartman compiler
  set(GAME_LINKED ${TARGET_NAME}.elf) # Intermediate executable
  set(GAME_EXE ${TARGET_NAME}.exe) # Use this to launch the game
  add_executable(${GAME_LINKED} ${SOURCES} ${HEADERS})
  add_custom_command(
    TARGET ${GAME_LINKED} POST_BUILD
    COMMAND ${ELF2HUNK} ${GAME_LINKED} ${GAME_EXE}
  )
else()
  # Just produce the executable with Bebbo compiler
  SET(GAME_LINKED ${TARGET_NAME})
  SET(GAME_EXE ${TARGET_NAME})
  add_executable(${GAME_LINKED} ${SOURCES} ${HEADERS})
endif()

target_link_libraries(${GAME_LINKED} ace)
```

--------------------------------

### Amiga "Hello world" C Code

Source: https://github.com/amigaports/ace/blob/main/docs/programming/hello_world.md

This C code is a basic "Hello world" example for Amiga using the ACE library. It includes functions for initialization (genericCreate), frame processing (genericProcess), and cleanup (genericDestroy). Logging is enabled via GENERIC_MAIN_LOG_PATH.

```c
#define GENERIC_MAIN_LOG_PATH "game.log"

#include <ace/generic/main.h>

void genericCreate(void) {
  // Here goes your startup code
  logWrite("Hello, Amiga!\n");
}

void genericProcess(void) {
  // Here goes code done each game frame
  // Nothing here right now
  gameExit();
}

void genericDestroy(void) {
  // Here goes your cleanup code
  logWrite("Goodbye, Amiga!\n");
}
```

--------------------------------

### Install Latest Bartman's VSCode Extension from VSIX

Source: https://github.com/amigaports/ace/blob/main/docs/installing/compiler.md

Steps to install the newest version of Bartman's Amiga Debug extension by downloading the .vsix file from GitHub releases and installing it manually in VSCode.

```plaintext
Navigate to [GitHub Releases](https://github.com/BartmanAbyss/vscode-amiga-debug/releases) page,
download latest .vsix file
in VSCode, enter Extensions tab (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>X</kbd>), select "..." icon and select "Install from VSIX..." option.
```

--------------------------------

### AmigaPorts ACE CMake Kit Configuration for GCC

Source: https://github.com/amigaports/ace/blob/main/docs/installing/compiler.md

Example CMake kit configuration for Visual Studio Code to integrate Bebbo's GCC compiler for AmigaOS development. This setup specifies compiler paths, toolchain files, and relevant CMake settings for cross-compilation targeting m68k-amigaos.

```JSON
[
  {
    "name": "Some other compiler which was automatically detected",
    "//": "Some other fields..."
  },
  {
    "name": "GCC for m68k-amigaos 6.5.0b",
    "compilers": {
      "C": "/opt/amiga/bin/m68k-amigaos-gcc",
      "CXX": "/opt/amiga/bin/m68k-amigaos-g++"
    },
    "toolchainFile": "/path/to/AmigaCMakeCrossToolchains/m68k-amigaos.cmake",
    "cmakeSettings": {
      "M68K_CPU": "68000",
      "M68K_FPU": "soft",
      "M68K_CRT": "nix13",
      "TOOLCHAIN_PREFIX": "m68k-amigaos",
      "TOOLCHAIN_PATH": "/opt/amiga"
    }
  }
]
```

--------------------------------

### C Include Guard Example

Source: https://github.com/amigaports/ace/blob/main/docs/contributing/codestyle.md

Provides an example of a standard include guard for C header files, incorporating the project name and filesystem path for uniqueness.

```c
#ifndef _ACE_MANAGERS_BLIT_H_
#define _ACE_MANAGERS_BLIT_H_

// stuff

#endif // _ACE_MANAGERS_BLIT_H_
```

--------------------------------

### C Include Order Example

Source: https://github.com/amigaports/ace/blob/main/docs/contributing/codestyle.md

Illustrates the recommended order for include directives in C source files, prioritizing local headers, standard libraries, project-specific libraries, and finally other project files.

```c
#include "main.h"
#include <stdlib.h>
#include <ace/managers/memory.h>
#include <ace/managers/log.h>
#include <ace/managers/timer.h>
#include <ace/utils/palette.h>
#include "menu/menu.h"
#include "input.h"
```

--------------------------------

### Initialize and Configure PTPlayer

Source: https://github.com/amigaports/ace/blob/main/docs/programming/audio.md

Initializes PTPlayer, sets music channel reservations, master volume, and song repeat behavior. This setup is typically done in the main or gamestate create function.

```c
// Initialize (1 = PAL mode, 0 = NTSC)
ptplayerCreate(1);

// Optional: Configure which channels are reserved for music
ptplayerSetMusicChannelMask(0b0011);  // Reserves channels 0 and 1 for music

// Optional: Set master volume
ptplayerSetMasterVolume(48);  // Range is 0-64

// Optional: Configure song repeat behavior
ptplayerConfigureSongRepeat(1, onSongEnd);
```

--------------------------------

### Amiga "Hello world" Build with Terminal Commands

Source: https://github.com/amigaports/ace/blob/main/docs/programming/hello_world.md

This section provides terminal commands to build the Amiga "Hello world" project using CMake. It covers creating a build directory, configuring the project with specific toolchain paths and debug flags, and executing the build process.

```sh
mkdir build && cd build
# Add optional -DACE_DEBUG_UAE=ON for better debugging experience under emulator
cmake .. \
  -DCMAKE_TOOLCHAIN_FILE=/path/to/AmigaCMakeCrossToolchains/m68k.cmake \
  -DM68K_TOOLCHAIN_PATH=/path/to/toolchain \
  -DM68K_CPU=68000 -DM68K_FPU=soft -DACE_DEBUG=ON
cmake --build .
```

--------------------------------

### Generic Main File Setup

Source: https://github.com/amigaports/ace/blob/main/docs/programming/ace_in_a_nutshell.md

Demonstrates how to use the generic main file provided by the ACE library to reduce boilerplate code in game development. It outlines the required functions (genericCreate, genericProcess, genericDestroy) and how to customize the main loop condition.

```c
#define GENERIC_MAIN_LOOP_CONDITION g_pGameStateManager->pCurrent
#include <ace/generic/main.h>
```

--------------------------------

### Install Bartman's VSCode Extension

Source: https://github.com/amigaports/ace/blob/main/docs/installing/compiler.md

Instructions for installing Bartman's Amiga Debug extension from the Visual Studio Code Marketplace. This extension includes the GCC compiler and debugging features.

```plaintext
In VSCode go to Extensions page and install `bartmanabyss.amiga-debug` extension.
```

--------------------------------

### Cygwin Launch Shortcut for Bebbo's Compiler

Source: https://github.com/amigaports/ace/blob/main/docs/installing/compiler.md

This command sets up a Windows shortcut to launch a command prompt with Bebbo's compiler and Cygwin paths configured in the environment variables. It ensures that the necessary tools are available for building ACE or Bebbo's compiler.

```plain
C:\WINDOWS\system32\cmd.exe /c "SET PATH=path/to/bebbo/bin;path/to/cygwin/bin;%PATH%&& set PREFIX=/cygdrive/path/to/bebbo&& START cmd.exe"
```

--------------------------------

### Amiga ACE Game State Header File (C)

Source: https://github.com/amigaports/ace/blob/main/docs/programming/hello_world.md

This C header file (`game.h`) declares the functions related to the game state (`gameGsCreate`, `gameGsLoop`, `gameGsDestroy`) that are defined in `game.c`. It uses include guards to prevent multiple inclusions and ensure proper compilation.

```c
#ifndef _GAME_H_
#define _GAME_H_

// Function headers from game.c go here
// It's best to put here only those functions which are needed in other files.

void gameGsCreate(void);
void gameGsLoop(void);
void gameGsDestroy(void);

#endif // _GAME_H_
```

--------------------------------

### ACE Installation and Functions Inclusion

Source: https://github.com/amigaports/ace/blob/main/CMakeLists.txt

Includes CMake scripts for handling the installation of the ACE project and for defining custom ACE-specific functions.

```CMake
include(cmake/ace_install.cmake)
include(cmake/ace_functions.cmake)
```

--------------------------------

### Amiga ACE Main Program Integration (C)

Source: https://github.com/amigaports/ace/blob/main/docs/programming/hello_world.md

This C code integrates the game state into the main program flow of an Amiga ACE application. It initializes the key manager, state manager, and the specific game state, then pushes it onto the state manager. The `genericProcess` function handles frame-by-frame updates for keys and states, while `genericDestroy` cleans up resources.

```c
// Use this only if you want to enable logging to file instead of UAE console (heavy performance hit, not recommended)
#define GENERIC_MAIN_LOG_PATH "game.log"

#include <ace/generic/main.h>
#include <ace/managers/key.h>
#include <ace/managers/state.h>
// Without it compiler will yell about undeclared gameGsCreate etc
#include "game.h"

tStateManager *g_pGameStateManager = 0;
tState *g_pGameState = 0;

void genericCreate(void) {
  // Here goes your startup code
  logWrite("Hello, Amiga!\n");
  keyCreate(); // We'll use keyboard
  // Initialize gamestate
  g_pGameStateManager = stateManagerCreate();
  g_pGameState = stateCreate(gameGsCreate, gameGsLoop, gameGsDestroy, 0, 0);

  statePush(g_pGameStateManager, g_pGameState);
}

void genericProcess(void) {
  // Here goes code done each game frame
  keyProcess();
  stateProcess(g_pGameStateManager); // Process current gamestate's loop
}

void genericDestroy(void) {
  // Here goes your cleanup code
  stateManagerDestroy(g_pGameStateManager);
  stateDestroy(g_pGameState);
  keyDestroy(); // We don't need it anymore
  logWrite("Goodbye, Amiga!\n");
}
```

--------------------------------

### Amiga ACE BOB Setup: Simple Buffer Creation

Source: https://github.com/amigaports/ace/blob/main/docs/programming/using_bobs.md

Demonstrates how to create a simple buffer viewport manager for Amiga ACE BOBs, enabling double buffering and interleaved bitmaps for optimal performance.

```c
// Create a simple buffer viewport manager with double buffering and interleaved bitmap
s_pVpManager = simpleBufferCreate(0,
   TAG_SIMPLEBUFFER_BITMAP_FLAGS, BMF_CLEAR | BMF_INTERLEAVED,
   TAG_SIMPLEBUFFER_IS_DBLBUF, 1,
   // Add other tags as needed
TAG_DONE);

```

--------------------------------

### Amiga ACE Game State Initialization and Loop (C)

Source: https://github.com/amigaports/ace/blob/main/docs/programming/hello_world.md

This C code defines the core functions for a game state in the Amiga ACE framework. It includes `gameGsCreate` for initialization, `gameGsLoop` for the game loop logic (checking for ESC key press to exit), and `gameGsDestroy` for cleanup. It also utilizes managers for keys, game exit, and system operations.

```c
#include "game.h"
#include <ace/managers/key.h> // We'll use key* fns here
#include <ace/managers/game.h> // For using gameExit
#include <ace/managers/system.h> // For systemUnuse and systemUse

// "Gamestate" is a long word, so let's use shortcut "Gs" when naming fns

void gameGsCreate(void) {
  // Initializations for this gamestate - load bitmaps, draw background, etc.
  // We don't need anything here right now except for unusing OS
  systemUnuse();
}

void gameGsLoop(void) {
  // This will loop forever until you "pop" or change gamestate
  // or close the game
  if(keyCheck(KEY_ESCAPE)) {
    gameExit();
  }
  else {
    // Process loop normally
    // We'll come back here later
  }
}

void gameGsDestroy(void) {
  systemUse();
  // Cleanup when leaving this gamestate
  // Empty at the moment except systemUse
}
```

--------------------------------

### Manual OS State Management in ACE

Source: https://github.com/amigaports/ace/blob/main/docs/programming/os.md

Demonstrates how to manually manage AmigaOS state for performance. The first example shows inefficient OS re-enabling for each function call. The second example shows the optimized approach by enabling OS once before a block of OS-dependent functions and disabling it afterwards.

```c
systemUnuse(); // Assume that OS is disabled at this point

logWrite("I'm initializing stuff\n");
paletteLoadFromPath("palette.plt", s_pPalette, 32);
s_pBm1 = bitmapCreate(320, 256, 5);
s_pBm2 = fontCreate("test.fnt");
logWrite("I'm done initializing\n");
```

```c
systemUse(); // Re-enable OS once
logWrite("I'm initializing stuff\n");       // Any of these functions
paletteLoadFromPath("palette.plt", s_pPalette, 32); // Won't re-enable/disable OS
s_pBm1 = bitmapCreate(320, 256, 5);         // They have systemUse()/systemUnuse calls
s_pBm2 = fontCreate("test.fnt");            // But they won't do anything since OS
logWrite("I'm done initializing\n");        // Is already enabled
systemUnuse(); // Disable OS once when we're done with it
```

--------------------------------

### ACE Project Setup and Configuration

Source: https://github.com/amigaports/ace/blob/main/CMakeLists.txt

Configures the ACE project using CMake, setting the minimum version, project name, language, description, and homepage. It also handles directory scoping and defines the project version.

```CMake
cmake_minimum_required(VERSION 3.14.0)
project(ACE
	LANGUAGES C
	DESCRIPTION "Amiga C Engine"
	HOMEPAGE_URL "https://github.com/AmigaPorts/ACE"
)

# TODO: replace with PROJECT_IS_TOP_LEVEL with cmake 3.21+
get_directory_property(hasParent PARENT_DIRECTORY)
if(hasParent)
	# needed for helper fns
	set(ACE_DIR ${CMAKE_CURRENT_LIST_DIR} PARENT_SCOPE)
else()
	set(ACE_DIR ${CMAKE_CURRENT_LIST_DIR})
endif()

# Adhere to GNU filesystem layout conventions
include(GNUInstallDirs)

# Lowercase project name for binaries and packaging
string(TOLOWER ${PROJECT_NAME} PROJECT_NAME_LOWER)

# Version number in format X.Y.Z
set(VER_X 0)
set(VER_Y 0)
set(VER_Z 1)
set(VER_FULL "${VER_X}.${VER_Y}.${VER_Z}")

if(NOT AMIGA)
	message(SEND_ERROR "[ACE] This project only compiles for Amiga")
endif()
```

--------------------------------

### Amiga Ace Game Initialization (C)

Source: https://github.com/amigaports/ace/blob/main/docs/programming/tilebuffer.md

Sets up the game environment within the `gameGsCreate` function. This includes initializing input systems, creating views and viewports for score and main playfields, loading tile assets, setting up the tile buffer manager with scrolling capabilities, loading palettes, and initiating map loading and camera setup.

```c
// To move scrolling
keyCreate();
joyOpen();

s_pView = viewCreate(0, TAG_END);

// Viewport for score bar - on top of screen
s_pVpScore = vPortCreate(0,
    TAG_VPORT_VIEW, s_pView,
    TAG_VPORT_BPP, GAME_BPP,
vTAG_VPORT_HEIGHT, SCORE_HEIGHT,
TAG_END);

s_pScoreBuffer = simpleBufferCreate(0,
    TAG_SIMPLEBUFFER_VPORT, s_pVpScore,
    TAG_SIMPLEBUFFER_BITMAP_FLAGS, BMF_CLEAR,
    TAG_SIMPLEBUFFER_BOUND_WIDTH, 320,
    TAG_SIMPLEBUFFER_BOUND_HEIGHT, SCORE_HEIGHT,
TAG_END);

// Now let's do the same for main playfield where the scrolling happen
s_pVpMain = vPortCreate(0,
    TAG_VPORT_VIEW, s_pView,
    TAG_VPORT_BPP, GAME_BPP,
TAG_END);

// Load tiles
s_pTiles = bitmapCreateFromPath("data/overworld.bm", 0);

logWrite("Tiles Loaded!\n");

// Init your scrolling tile buffer 
s_pMainBuffer = tileBufferCreate(0,
    TAG_TILEBUFFER_VPORT, s_pVpMain,  // Select View Port
    TAG_TILEBUFFER_BITMAP_FLAGS, BMF_CLEAR | BMF_INTERLEAVED,  // If you put interleaved there, it should be also in your cmakelist part.
    TAG_TILEBUFFER_BOUND_TILE_X, TILE_MAP_SIZE_X, // Map size in number of tile
    TAG_TILEBUFFER_BOUND_TILE_Y, TILE_MAP_SIZE_Y, // Map size in number of tile
    TAG_TILEBUFFER_IS_DBLBUF, 1, // Activatey double buffering
    TAG_TILEBUFFER_TILE_SHIFT, 4, //Size of tile, given in bitshift. Set to 4 for 16px, 5 for 32px, etc. Mandatory.
    TAG_TILEBUFFER_REDRAW_QUEUE_LENGTH, 200, // cursor between handling fast scrolling versus your amiga power
    TAG_TILEBUFFER_CALLBACK_TILE_DRAW, onTileDraw, // To be documented
    TAG_TILEBUFFER_TILESET, s_pTiles,
TAG_END);


// Load and apply palette
paletteLoadFromPath("data/overworld.plt", s_pPalette, 1 << GAME_BPP);
memcpy(s_pVpScore->pPalette, s_pPalette, sizeof(s_pVpScore->pPalette));
memcpy(s_pVpMain->pPalette, s_pPalette, sizeof(s_pVpMain->pPalette));


loadMap();

//IO operations end here - let's unload the OS and display some stuff
systemUnuse();

logWrite("Camera Reset\n");
cameraReset(s_pMainBuffer->pCamera, 0, 0, s_uwMapTileWidth*16, s_uwMapTileHeight * 16, 1);

// Initial draw
tileBufferRedrawAll(s_pMainBuffer);

// Set initial camera
cameraSetCoord(s_pMainBuffer->pCamera, g_uwCameraX, g_uwCameraY);

// Load & Display the view
viewLoad(s_pView);
```

--------------------------------

### Complex State Management Example

Source: https://github.com/amigaports/ace/blob/main/docs/programming/ace_in_a_nutshell.md

Illustrates a state machine pattern for managing complex menu states in an application. It shows how to transition between different menu states like menuCommon, menuMain, menuOptions, and menuMapSelect, including pushing and popping states.

```plain
                     |--POP-----------  menuMapSelect
                     |                     | ^
                     |               CHANGE| |CHANGE
                     v                     v |
OS  --CREATE-->  menuCommon  --PUSH-->  menuMain
                   | ^                     | ^
             CHANGE| |CHANGE         CHANGE| |CHANGE
                   v |                     v |
                  game                  menuOptions
```

--------------------------------

### Checking PATH on Windows

Source: https://github.com/amigaports/ace/blob/main/docs/installing/compiler.md

Command to verify if the mingw32-make executable is correctly added to the system's PATH environment variable on Windows.

```bash
where mingw32-make
```

--------------------------------

### Amiga ACE Sprite Manager Setup and Usage

Source: https://github.com/amigaports/ace/blob/main/docs/programming/sprites.md

Demonstrates the initialization, DMA enabling, and per-channel processing required for the Amiga ACE sprite manager. It shows how to create, destroy, and process sprite channels within a typical game loop structure.

```C
void myGsCreate(void) {
  // Some stuff goes here...

  spriteManagerCreate(s_pView, 0, NULL); // For raw copper mode, pass position on
                                         // copperlist for sprite initialization.
  systemSetDmaBit(DMAB_SPRITE, 1); // Enable sprite DMA.

  // Stuff continues...
}

void myGsDestroy(void) {
  // Some stuff goes here...

  systemSetDmaBit(DMAB_SPRITE, 0); // Disable sprite DMA
  spriteManagerDestroy();

  // Stuff continues...
}

void myGsLoop(void) {
  // Some stuff goes here...

  // Before you call copProcessBlocks():
  spriteProcessChannel(0); // Process first sprite channel...
  spriteProcessChannel(3); // ...and the fourth one.

  // Stuff continues...

  copProcessBlocks(); // Be sure to call it or sprite-related copper commands won't work!
  vPortWaitForEnd(s_pVp);
}
```

--------------------------------

### AmigaOS ACE Tile Buffer Callback Example

Source: https://github.com/amigaports/ace/blob/main/docs/programming/using_bobs.md

Demonstrates how to set up a tile callback function for the AmigaOS ACE Tile Buffer to update the Pristine Buffer. The `onTileDraw` function copies a tile's bitmap to the pristine buffer, and `tileBufferCreate` initializes the buffer with this callback.

```C
static void onTileDraw(
   UNUSED_ARG UWORD uwTileX, UNUSED_ARG UWORD uwTileY,
   tBitMap *pBitMap, UWORD uwBitMapX, UWORD uwBitMapY
) {
   blitCopyAligned(
      pBitMap, uwBitMapX, uwBitMapY,
      s_pPristineBuffer, uwBitMapX, uwBitMapY, TILE_SIZE, TILE_SIZE
   );
}

// Initialize the Tile Buffer with following:
g_pMainBuffer = tileBufferCreate(0,
   TAG_TILEBUFFER_CALLBACK_TILE_DRAW, onTileDraw,
   // ... other tags here
TAG_END);

```

--------------------------------

### VSCode CMake Kits Configuration

Source: https://github.com/amigaports/ace/blob/main/docs/installing/compiler.md

Configuration for VSCode's CMake Tools extension to recognize Bartman's compiler toolchains for Amiga development. Includes settings for Windows (MinGW) and Unix-like systems, specifying toolchain files, environment variables, preferred generators, and CMake settings.

```json
[
  {
    "name": "GCC Bartman m68k Win32",
    "toolchainFile": "${workspaceFolder}/../AmigaCMakeCrossToolchains/m68k-bartman.cmake",
    "environmentVariables": {
      "PATH": "${command:amiga.bin-path}/opt/bin;${command:amiga.bin-path};${command:amiga.bin-path}/opt/m68k-amiga-elf/bin;${env:PATH}"
    },
    "preferredGenerator": {
      "name": "MinGW Makefiles"
    },
    "cmakeSettings": {
      "M68K_CPU": "68000",
      "TOOLCHAIN_PREFIX": "m68k-amiga-elf",
      "TOOLCHAIN_PATH": "${command:amiga.bin-path}/opt"
    },
    "keep": true
  },
  {
    "name": "GCC Bartman m68k Unix",
    "toolchainFile": "${workspaceFolder}/deps/AmigaCMakeCrossToolchains/m68k-bartman.cmake",
    "environmentVariables": {
      "PATH": "${command:amiga.bin-path}/opt/bin:${command:amiga.bin-path}:${command:amiga.bin-path}/opt/m68k-amiga-elf/bin:${env:PATH}"
    },
    "preferredGenerator": {
      "name": "Unix Makefiles"
    },
    "cmakeSettings": {
      "M68K_CPU": "68000",
      "TOOLCHAIN_PREFIX": "m68k-amiga-elf",
      "TOOLCHAIN_PATH": "${command:amiga.bin-path}/opt"
    },
    "keep": true
  }
]
```

--------------------------------

### Build and Run ACE Showcase with CMake

Source: https://github.com/amigaports/ace/blob/main/showcase/README.md

This snippet demonstrates how to build and run the ACE Showcase project using CMake. It includes setting up the build directory, configuring CMake with a specific toolchain file and target CPU, and then building the project. The 'data' directory must be present in the current working directory for the showcase to run.

```sh
mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/AmigaCMakeCrossToolchains/m68k.cmake -DM68K_TOOLCHAIN_PATH=/path/to/toolchain -DM68K_CPU=68000 -DM68K_FPU=soft
make
```

--------------------------------

### Play MOD Music with PTPlayer

Source: https://github.com/amigaports/ace/blob/main/docs/programming/audio.md

Loads a MOD file and starts music playback. This function is used to play music within the game loop.

```c
// Load a MOD file
tPtplayerMod *pMod = ptplayerModCreateFromPath("music.mod");

// Start playback (2nd parameter is NULL to use samples from inside the MOD file, set start position to 0)
ptplayerLoadMod(pMod, NULL, 0);

// Enable music playback
ptplayerEnableMusic(1);
```

--------------------------------

### CMake Build Options for ACE

Source: https://github.com/amigaports/ace/blob/main/docs/installing/ace.md

Illustrates various CMake build options for ACE, including specifying CPU, FPU, debug builds, and static library creation.

```cmake
-DM68K_CPU=68000
-DM68K_FPU=soft
-DCMAKE_BUILD_TYPE=Debug
-DACE_BUILD_KIND=STATIC
```

--------------------------------

### Load Palette and Background Graphics in Amiga ACE

Source: https://github.com/amigaports/ace/blob/main/docs/programming/loading_images.md

Demonstrates loading a color palette from a file and drawing a background image onto the screen using the Amiga ACE framework. It includes steps for initializing the palette, creating a bitmap from a file, blitting the bitmap to the screen buffer, and cleaning up the bitmap resource. This is essential for setting up the game's visual environment.

```c
#include <ace/utils/palette.h>

void gameGsCreate(void) {
  // ...old stuff here...

//-------------------------------------------------------------- NEW STUFF START
  // Load palette from file to first viewport - second one will use the same
  // due to TAG_VIEW_GLOBAL_PALETTE being by default set to 1. We're using
  // 4BPP display, which means max 16 colors.
  paletteLoadFromPath("data/pong.plt", s_pVpScore->pPalette, 16);

  // Load background graphics and draw them immediately
  tBitMap *pBmBackground = bitmapCreateFromPath("data/pong_bg.bm", 0);
  for(UWORD uwX = 0; uwX < s_pMainBuffer->uBfrBounds.uwX; uwX += 16) {
    for(UWORD uwY = 0; uwY < s_pMainBuffer->uBfrBounds.uwY; uwY += 16) {
      blitCopyAligned(pBmBackground, 0, 0, s_pMainBuffer->pBack, uwX, uwY, 16, 16);
    }
  }
  bitmapDestroy(pBmBackground);
//---------------------------------------------------------------- NEW STUFF END

  // Draw line separating score VPort and main VPort, leave one line blank after it
  blitLine(
    s_pScoreBuffer->pBack,
    0, s_pVpScore->uwHeight - 2,
    s_pVpScore->uwWidth - 1, s_pVpScore->uwHeight - 2,
    SCORE_COLOR, 0xFFFF, 0 // Try patterns 0xAAAA, 0xEEEE, etc.
  );

  // NEW: Don't need the line for bottom wall anymore

  systemUnuse();

  // Load the view
  viewLoad(s_pView);
}
```

--------------------------------

### Checking PATH on Linux/macOS

Source: https://github.com/amigaports/ace/blob/main/docs/installing/compiler.md

Command to verify if the cmake executable is correctly added to the system's PATH environment variable on Linux or macOS.

```bash
which cmake
```

--------------------------------

### C Struct Typedef Convention

Source: https://github.com/amigaports/ace/blob/main/docs/contributing/codestyle.md

Demonstrates the convention for defining and typedef-ing structs in C, ensuring a consistent naming pattern for struct instances.

```c
typedef struct _tTypeName {

} tTypeName;
```

--------------------------------

### Change Advanced Sprite Frame

Source: https://github.com/amigaports/ace/blob/main/docs/programming/advancedsprites.md

Allows changing the currently displayed frame of an advanced sprite, which is useful for animation or state changes. Frame numbering starts at 0.

```c
// 5 is the frame number starting at 0
advancedSpriteSetFrame(s_pASprite,5);
```

--------------------------------

### C Code Formatting: Braces and Indentation

Source: https://github.com/amigaports/ace/blob/main/docs/contributing/codestyle.md

Defines the standard for brace placement (one true brace) and indentation (tabs or spaces) in C code. It also covers the preferred style for control statements and switch cases.

```c
void someFn(void) {
  if(stuff) {

  }
  else {

  }

  // the only case when control statement body is in same line
  while(someEvent()) continue;

  do {
    // stuff
  } while(condition);

  switch(var) {
    case
  }
}
```

--------------------------------

### ACE Resource Management (Utils)

Source: https://github.com/amigaports/ace/blob/main/docs/programming/ace_in_a_nutshell.md

Demonstrates how to create and manage resources using ACE's utility functions. Resources are created via dedicated functions (e.g., bitmapCreate) and must be freed using corresponding destroy functions (e.g., bitmapDestroy). Utility functions operate on these resources by passing them as parameters.

```C
/* Example of creating and using a bitmap resource */
Bitmap* pBm = bitmapCreate(width, height, depth);
if (pBm) {
    /* Use bitmap functions */
    int byteWidth = bitmapGetByteWidth(pBm);
    /* ... other operations ... */

    /* Free the resource when done */
    bitmapDestroy(pBm);
}
```

--------------------------------

### C Function Signature Formatting for Readability

Source: https://github.com/amigaports/ace/blob/main/docs/contributing/codestyle.md

Illustrates how to format C function signatures, especially those with many arguments, to improve readability and adhere to horizontal character limits. This includes breaking long argument lists across multiple lines.

```c
void fnShort(t1 arg1, t2 fnNameAndArgsFitInOneLine);

void fnWithManyArgs(
  t1 arg1, t2 arg2, t3 allArgsFitInOneLineButWithoutFnName
);

void fnWithTooManyArgs(
  t1 arg1, t2 arg2, t3 thereAreTooManyFnArgsToFitInOneLine,
  t4 arg4, t5 arg5, t6 soArgListIsBrokenToMultipleLines
);
```

--------------------------------

### VS Code Debugger Configuration for Amiga

Source: https://github.com/amigaports/ace/blob/main/docs/installing/compiler.md

This JSON configuration sets up the debugger in VS Code for Amiga development. It defines launch configurations for Amiga 500 and Amiga 1200, specifying the program executable, kickstart ROM paths, and other emulator settings.

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "amiga",
      "request": "launch",
      "name": "Amiga 500",
      "config": "A500",
      "program": "${workspaceFolder}/build/myGame",
      "kickstart": "/path/to/kick13.rom",
      "internalConsoleOptions": "openOnSessionStart"
    },
    {
      "type": "amiga",
      "request": "launch",
      "name": "Amiga 1200",
      "config": "A1200",
      "program": "${workspaceFolder}/build/myGame",
      "kickstart": "/path/to/kick31.rom",
      "internalConsoleOptions": "openOnSessionStart"
    }
  ]
}
```

--------------------------------

### Build Standalone ACE Library

Source: https://github.com/amigaports/ace/blob/main/docs/installing/ace.md

Builds ACE as a standalone library using CMake, specifying the toolchain file, CPU, FPU, and build options.

```shell
mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/AmigaCMakeCrossToolchains/m68k.cmake -DM68K_TOOLCHAIN_PATH=/path/to/toolchain -DM68K_CPU=68000 -DM68K_FPU=soft
make
```

--------------------------------

### Advanced PTPlayer Features

Source: https://github.com/amigaports/ace/blob/main/docs/programming/audio.md

Demonstrates advanced functionalities of PTPlayer, including synchronizing game events with music using the E8 command, loading sample packs for MOD files, and adjusting individual music sample volumes.

```c
// Retrieve the last E8 value for synchronizing game events with music
ptplayerGetE8();

// Load sample data from a sample pack to save memory when using multiple songs with shared samples
// ptplayerSampleDataCreateFromPath("samples.pak");
// Pass the sample data in the 2nd parameter of ptplayerLoadMod()

// Adjust individual music sample volumes even when music is playing
// ptplayerSetSampleVolume(sample_index, volume);
```

--------------------------------

### Amiga Ace Game Constants and Variables (C)

Source: https://github.com/amigaports/ace/blob/main/docs/programming/tilebuffer.md

Defines essential constants and static variables for game configuration, including tile map dimensions, bits per pixel, score display height, and pointers to viewports and buffer managers. These are foundational for game setup.

```c
#define TILE_MAP_SIZE_X 200
#define TILE_MAP_SIZE_Y 80
#define GAME_BPP 5 // 32 colors
#define SCORE_HEIGHT 16

// View containing all the viewports
static tView *s_pView;
// For score - won't be used in this tuto
static tVPort *s_pVpScore; // Viewport for score
static tSimpleBufferManager *s_pScoreBuffer;
// Viewport for playfield
static tVPort *s_pVpMain;
// Your buffer manager, it will handle your scrolling
static tTileBufferManager *s_pMainBuffer;
// Tiles
static tBitMap *s_pTiles;
// Palette
static UWORD s_pPalette[1 << GAME_BPP];

static UWORD s_uwMapTileWidth;
static UWORD s_uwMapTileHeight;
// To controle camera/view on scrolling
UWORD g_uwCameraX=0;
UWORD g_uwCameraY=0;
UWORD g_uwCameraSpeed=2;
```

--------------------------------

### Add ACE as Git Submodule

Source: https://github.com/amigaports/ace/blob/main/docs/installing/ace.md

Adds the ACE repository as a Git submodule to your project's dependencies directory, allowing for version-controlled integration.

```shell
mkdir deps
git submodule add https://github.com/AmigaPorts/ACE deps/ace
```

--------------------------------

### AmigaOS Ace: Create View and Viewports

Source: https://github.com/amigaports/ace/blob/main/docs/programming/view.md

Demonstrates the creation of a main view and two viewports (for score and playfield) using the Ace framework. It utilizes tag syntax for configuration, specifies BPP and height for viewports, and initializes simple buffer managers.

```c
#include "game.h"
#include <ace/managers/key.h> // Keyboard processing
#include <ace/managers/game.h> // For using gameExit
#include <ace/managers/system.h> // For systemUnuse and systemUse
#include <ace/managers/viewport/simplebuffer.h> // Simple buffer

// All variables outside fns are global - can be accessed in any fn
// Static means here that given var is only for this file, hence 's_' prefix
// You can have many variables with same name in different files and they'll be
// independent as long as they're static
// * means pointer, hence 'p' prefix
static tView *s_pView; // View containing all the viewports
static tVPort *s_pVpScore; // Viewport for score
static tSimpleBufferManager *s_pScoreBuffer;
static tVPort *s_pVpMain; // Viewport for playfield
static tSimpleBufferManager *s_pMainBuffer;

void gameGsCreate(void) {
  // Create a view - first arg is always zero, then it's option-value
  s_pView = viewCreate(0,
    // Same color palette for all viewports, can be skipped as it's set
    // by default to 1.
    TAG_VIEW_GLOBAL_PALETTE, 1,
  TAG_END); // Must always end with TAG_END or synonym: TAG_DONE

  // Viewport for score bar - on top of screen
  s_pVpScore = vPortCreate(0,
    TAG_VPORT_VIEW, s_pView, // Required: specify parent view
    TAG_VPORT_BPP, 4, // Optional: 4 bits per pixel, 16 colors
    TAG_VPORT_HEIGHT, 32, // Optional: let's make it 32px high
  TAG_END); // same syntax as view creation

  // Create simple buffer manager with bitmap exactly as large as viewport
  s_pScoreBuffer = simpleBufferCreate(0,
    TAG_SIMPLEBUFFER_VPORT, s_pVpScore, // Required: parent viewport
    // Optional: buffer bitmap creation flags
    // we'll use them to initially clear the bitmap
    TAG_SIMPLEBUFFER_BITMAP_FLAGS, BMF_CLEAR,
  TAG_END);

  // Now let's do the same for main playfield
  s_pVpMain = vPortCreate(0,
    TAG_VPORT_VIEW, s_pView,
    TAG_VPORT_BPP, 4, // 4 bits per pixel, 16 colors
    // We won't specify height here - viewport will take remaining space.
  TAG_END);
  s_pMainBuffer = simpleBufferCreate(0,
    TAG_SIMPLEBUFFER_VPORT, s_pVpMain, // Required: parent viewport
    TAG_SIMPLEBUFFER_BITMAP_FLAGS, BMF_CLEAR,
  TAG_END);

  // Since we've set up global palette, palette will be loaded from first viewport
  // Colors are 0x0RGB, each channel accepts values from 0 to 15 (0 to F).
  s_pVpScore->pPalette[0] = 0x0000; // First color is also border color
  s_pVpScore->pPalette[1] = 0x0888; // Gray
  s_pVpScore->pPalette[2] = 0x0800; // Red - not max, a bit dark
  s_pVpScore->pPalette[3] = 0x0008; // Blue - same brightness as red

  // We don't need anything from OS anymore
  systemUnuse();

  // Load the view
  viewLoad(s_pView);
}

void gameGsLoop(void) {
  // This will loop forever until you "pop" or change gamestate
  // or close the game
  if(keyCheck(KEY_ESCAPE)) {
    gameExit();
  }
  else {
    // Process loop normally
    // We'll come back here later
  }
}

void gameGsDestroy(void) {
  // Cleanup when leaving this gamestate
  systemUse();

  // This will also destroy all associated viewports and viewport managers
  viewDestroy(s_pView);
}

```

--------------------------------

### Build ACE Tools with CMake

Source: https://github.com/amigaports/ace/blob/main/docs/installing/tools.md

Commands to build ACE tools using CMake. This includes creating a build directory, setting compiler paths for macOS, configuring CMake for different environments (GCC, MinGW GCC), and initiating the build process.

```shell
mkdir build && cd build

# When using MacOS (to avoid Clang) - assuming you have: brew install gcc@13
export CC=/usr/local/bin/gcc-13
export CXX=/usr/local/bin/g++-13

# When using GCC on Linux, MacOS or MSVC on Windows:
cmake ..
# When using MinGW GCC on Windows:
cmake .. -G "MinGW Makefiles"

cmake --build .
```

--------------------------------

### Basic Logging with logWrite

Source: https://github.com/amigaports/ace/blob/main/docs/programming/ace_in_a_nutshell.md

Shows how to use the `logWrite()` function for basic debugging output in the ACE library. It demonstrates writing formatted strings to the game log, emphasizing the need to manually add newline characters.

```c
logWrite("Hello, my favourite number is %d\n", 8);
// outputs in game.log: "Hello, my favourite number is 8"
```