### Casting Example

Source: https://github.com/alicelr/megazeux/blob/master/docs/STYLE.md

Illustrates the correct syntax for casting in C.

```c
int an_int = (int)not_an_int;

```

```c
int *an_int_ptr = (int *)not_an_int_ptr;

```

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

### Struct Array Initialization Example

Source: https://github.com/alicelr/megazeux/blob/master/docs/STYLE.md

Example of initializing a static array of structs, demonstrating tabulation for alignment.

```c
static const struct function_counter builtin_counters[] =
{
  { "$*",               V262,   string_counter_read,  string_counter_write },
  { "abs!",             V268,   abs_read,             NULL },
  { "acos!",            V268,   acos_read,            NULL },
  { "arctan!,!",        V284,   atan2_read,           NULL },

```

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

### Install MegaZeux

Source: https://github.com/alicelr/megazeux/blob/master/BUILDING.md

Install MegaZeux to the configured installation root. This command typically requires superuser privileges.

```shell
make install
```

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

### Video Layer Setup

Source: https://github.com/alicelr/megazeux/blob/master/contrib/mzvplay/mzvplay.txt

Initializes video layer dimensions and sprite reference offsets.

```MegaZeux Script
: "#vlayer"
set "vlayer_size" to "('mzv_vw'*'mzv_vh')"
set "vlayer_width" to "mzv_vw"
. "Sprite reference offsets."
set "mzv_vx" to 0
set "mzv_vy" to 0
set "mzv_vo" to 256
. "Current sprite index."
set "mzv_idx" to 0
goto "#return"
```

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

### Build and Install MegaZeux

Source: https://context7.com/alicelr/megazeux/llms.txt

Compile the MegaZeux engine using GNU Make after configuration. Supports parallel builds with the `-j` flag. Installation is done via `make install` to the configured prefix.

```bash
make -j8

```

```bash
sudo make install

```

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

### Install 3DS Libraries with Pacman

Source: https://github.com/alicelr/megazeux/blob/master/arch/3ds/README.md

Installs essential libraries for 3DS development using the pacman package manager. Ensure you have the 3ds-specific pacman configured.

```bash
pacman -S 3ds-libogg 3ds-libpng 3ds-libvorbisidec 3ds-zlib
```

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

### Shader Preprocessor Definitions

Source: https://github.com/alicelr/megazeux/blob/master/docs/STYLE.md

Example of preprocessor definitions used in a shader fragment file.

```glsl
#define SHARPEN_EDGES     1
#define MULTIPLIER        10.0

#define TEX_SCREEN_WIDTH  1024.0
#define TEX_SCREEN_HEIGHT 512.0
#define PIXEL_X           1.0 / TEX_SCREEN_WIDTH
#define PIXEL_Y           1.0 / TEX_SCREEN_HEIGHT
#define HALF_PIXEL_X      0.5 / TEX_SCREEN_WIDTH
#define HALF_PIXEL_Y      0.5 / TEX_SCREEN_HEIGHT

```

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

### MZX C-Style For Loop with Assignments

Source: https://github.com/alicelr/megazeux/blob/master/docs/exotic.txt

Provides an example of a C-style for loop in MZX, demonstrating initialization, condition, and increment expressions, including assignments and string operations.

```MZX
for ((x := 0) a ($str := "")) (x < 10) (x++)
  set $str ($str + x + " ")
* ~f&$str&
```

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

### Set Up a 2x2 Sprite

Source: https://github.com/alicelr/megazeux/blob/master/docs/WIPHelp.txt

Configure a sprite's reference characters, size, and initial position. Sprite number 15 is used as an example.

```text
~ASET "spr15_refx" 10
~ASET "spr15_refy" 10
~ASET "spr15_width" 2
~ASET "spr15_height" 2
~APUT c?? sprite p0f 40 5
```

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

### Initialize and Run MegaZeux Core Engine

Source: https://context7.com/alicelr/megazeux/llms.txt

This snippet shows the full engine startup process, including configuration, initialization of video and audio, core engine initialization, and running the main loop. It also includes cleanup after the core exits.

```c
#include "core.h"

// A simple custom context
static boolean my_draw(context *ctx)
{
  clear_screen();
  write_string("Custom screen — press Escape", 10, 12, 0x0F, WR_NONE);
  return true;  // return true to trigger screen update
}

static boolean my_key(context *ctx, int *key)
{
  if(*key == IKEY_ESCAPE)
  {
    destroy_context(ctx);
    return true;
  }
  return false;
}

void launch_my_screen(context *parent)
{
  // Allocate (or use stack) — NULL means the engine allocates internally
  struct context_spec spec = { 0 };
  spec.draw = my_draw;
  spec.key  = my_key;
  spec.framerate_mode = FRAMERATE_UI;

  create_context(NULL, parent, &spec, CTX_DIALOG_BOX);
}

// Full engine startup (used by MegaZeux's main())
int main(int argc, char *argv[])
{
  struct world mzx_world = { 0 };

  default_config();
  set_config_from_command_line(&argc, argv);

  struct config_info *conf = get_config();
  init_video(conf, "MegaZeux");
  init_audio(conf);

  core_context *root = core_init(&mzx_world);

  // Push the title screen context (done internally by MZX startup code)
  // create_context(NULL, (context*)root, &title_spec, CTX_TITLE_SCREEN);

  core_run(root);     // blocks until core_full_exit() is called

  core_free(root);
  quit_audio();
  quit_video();
  free_config();
  return 0;
}
```

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

### Initialize MZV Player

Source: https://github.com/alicelr/megazeux/blob/master/contrib/mzvplay/mzvplay.txt

Sets up the MZV player with initial parameters and loads the audio file.

```MegaZeux Script
set "$mzv_file" to "out.mzv"
mod "out.ogg"

set "mzx_speed" to 2
set "commands" to 10000
playercolor is c00
color c00
. "This audio synchronization wait is configuration and video dependent :("
. "wait for 4"
set "&$mzv_file&" to "fread_open"
goto "#play"
set "" to "fread_open"
end mod
end
```

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

### Initialize and Update Graphics in C

Source: https://context7.com/alicelr/megazeux/llms.txt

Set up the video system, draw characters and strings, manage layers, and update the screen. Supports standard and Super MZX modes, palette manipulation, and charset changes. Remember to call `update_screen()` to display changes and `quit_video()` on exit.

```c
#include "graphics.h"

// Initialize the video subsystem using the current config
struct config_info *conf = get_config();
init_video(conf, "My MegaZeux Game");  // caption shown on window title

// Draw a single character at (col, row) with given color byte
draw_char(0xDB /*█*/, 0x0F /*white on black*/, 10, 5);

// Write a null-terminated string
write_string("Hello MZX!", 5, 12, 0x0A /*bright green on black*/, WR_NONE);

// Write with color codes (~@) and newline support
write_string("~0fRed~07 and ~09Blue", 0, 0, 0x07, WR_COLOR | WR_NEWLINE);

// Fill a rectangle
fill_line(20,  5, 10, ' ', 0x1F);   // 20 spaces, starting at col 5, row 10

// Erase a rectangular region
erase_area(0, 20, 79, 24);

// Create an additional composited layer (e.g., UI overlay)
uint32_t layer_id = create_layer(
  0, 0,             // x, y position in character cells
  80, 25,           // width, height
  LAYER_DRAWORDER_UI, // draw order (higher = drawn on top)
  -1,               // transparent color (-1 = none)
  0,                // char offset
  false             // unbound (false = screen-space)
);
select_layer(layer_id);
draw_char('X', 0x4F, 0, 0);    // draw on the new layer
select_layer(UI_LAYER);         // switch back to default UI layer

// Palette operations
set_rgb(0, 0, 0, 0);            // color index 0 → black
set_rgb(15, 63, 63, 63);        // color index 15 → bright white (0-63 range)
get_rgb(15, &r, &g, &b);
set_palette_intensity(75);      // dim all colors to 75%

// SMZX mode
set_screen_mode(1);             // 0=MZX, 1-3=SMZX
set_smzx_index(5, 0, 255);     // palette 5, subpalette slot 0 → color index 255

// Charset manipulation
char matrix[14];                // CHAR_SIZE = 14 bytes per character (8×14 pixels)
ec_read_char(65, matrix);       // read char 'A'
matrix[0] ^= 0xFF;             // flip top row
ec_change_char(65, matrix);     // write it back

// Fade in/out
vquick_fadeout();
insta_fadein();

// Sync changes to the display
update_screen();

// Clean up
quit_video();

```

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

### Trigonometric Calculation Example

Source: https://github.com/alicelr/megazeux/blob/master/docs/exotic_translations.txt

Example showing a basic calculation using trigonometric functions.

```exotic
sin(val) * multiplier
```

```exotic
asin(val / divider)
```

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

### Enum Definition Example

Source: https://github.com/alicelr/megazeux/blob/master/docs/STYLE.md

Example of an enum definition using tabulation for readability, common in header files.

```c
enum mzx_version
{
  V100            = 0x0100, // Magic: MZX
  V200            = 0x0205, // Magic: MZ2
  V251            = 0x0205,
  ...
  VERSION_DECRYPT = 0x0211, // Special version used for decrypted worlds only.

```

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

### Configure and Manage Sprites via Counters

Source: https://context7.com/alicelr/megazeux/llms.txt

Demonstrates setting up sprite properties like position, dimensions, and visibility using the counter system. Includes examples for unbound sprites with pixel-precise control and collision detection. Ensure sprite headers are included.

```c
/* Sprites are primarily controlled through Robotic counters.
 * The following shows the C-level functions used by the engine. */

#include "sprite.h"
#include "sprite_struct.h"

struct sprite *spr = mzx_world->current_board->sprite_list[0];

// Set up sprite 0 via counter system (typical Robotic usage translated to C)
set_counter(mzx_world, "SPR0_X",      40, 0);   // column position
set_counter(mzx_world, "SPR0_Y",      12, 0);   // row position
set_counter(mzx_world, "SPR0_REFX",    0, 0);   // charset reference col
set_counter(mzx_world, "SPR0_REFY",    0, 0);   // charset reference row
set_counter(mzx_world, "SPR0_WIDTH",   2, 0);   // width in chars
set_counter(mzx_world, "SPR0_HEIGHT",  3, 0);   // height in chars
set_counter(mzx_world, "SPR0_OFF",     0, 0);   // 0=visible, 1=hidden

// Unbound sprite: pixel-precise positioning and collision
set_counter(mzx_world, "SPR0_UNBOUND", 1, 0);   // enable pixel mode
set_counter(mzx_world, "SPR0_TCOL",   32, 0);   // transparent char (space)

// Check collision at an arbitrary screen position
boolean hit = sprite_at_xy(mzx_world, spr, 10, 5);

// Find which sprite (if any) collides at (x, y), starting from sprite index 0
int colliding_id = sprite_colliding_xy(mzx_world, spr, 10, 5);
if(colliding_id >= 0)
  printf("Sprite %d collides\n", colliding_id);

// Draw all active sprites to the board layer (called once per frame by engine)
draw_sprites(mzx_world);

```

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

### Sprite Collision Example

Source: https://github.com/alicelr/megazeux/blob/master/docs/exotic_translations.txt

Example demonstrating how to use sprite collision detection to modify sprite position.

```exotic
if (~spr0_collides1,0)
  inc spr0_x 1
```

```exotic
if spr(0)_collides(a, b)
  * "~fouch"
```

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

### Display "HELLO WORLD!" in Robotic

Source: https://github.com/alicelr/megazeux/blob/master/docs/WIPHelp.txt

Use the ~E* command to display text on the bottom of the screen. This command executes immediately when the Robot's board is loaded. Always include the ~Eend command to properly terminate your code.

```Robotic
~E* "HELLO WORLD!"
~Eend
```

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

### Offset String Start

Source: https://github.com/alicelr/megazeux/blob/master/docs/WIPHelp.txt

Shifts the starting point of the string by a specified number of characters. Negative values offset from the end.

```RoboticScript
~B$strname+X~F
```

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

### Install Required MSYS2 Packages

Source: https://github.com/alicelr/megazeux/blob/master/scripts/buildscripts/README.md

Install essential build tools and libraries for PSP development using pacman in an MSYS2 MINGW64 terminal.

```bash
pacman --needed --noconfirm -S git svn wget patch tar unzip bzip2 xz diffutils python
pacman --needed --noconfirm -S autoconf automake cmake make m4 bison flex tcl texinfo doxygen
pacman --needed --noconfirm -S mingw-w64-x86_64-{gcc,SDL}
pacman --needed --noconfirm -S mingw-w64-x86_64-{libelf,libusb,ncurses,curl,gpgme,dlfcn}
pacman --needed --noconfirm -S mingw-w64-x86_64-{libarchive,openssl,readline,libtool}
```

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

### Prepare Release Environment Script

Source: https://github.com/alicelr/megazeux/blob/master/scripts/buildscripts/README.md

This script initializes the build environment by creating a working directory and cloning the MegaZeux repository. For MSYS2, it can also install necessary dependencies for Windows builds.

```bat
1_PrepareReleaseEnvironment.bat
```

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

### Initialize and Control Audio Playback

Source: https://context7.com/alicelr/megazeux/llms.txt

Initializes the audio system and demonstrates playback of music modules and sound samples. Includes volume control, looping, and PC speaker effects. Ensure audio is initialized before use and quit_audio() is called upon shutdown.

```c
#include "audio/audio.h"

// Initialize audio with the global config
struct config_info *conf = get_config();
init_audio(conf);     // sets up the platform mixer at conf->audio_sample_rate

// Play a module file (XM, IT, S3M, MOD, etc.)
// Returns 1 on success, 0 on failure
int ok = audio_play_module("dungeon.xm", true /*safe path*/, 8 /*volume 0-8*/);

// Adjust module volume at runtime
audio_set_module_volume(6);         // 0–8

// Query/seek the module
int order   = audio_get_module_order();
int pos     = audio_get_module_position();
audio_set_module_order(order + 1);  // skip to next pattern order
audio_set_module_position(0);       // restart current order

// Loop points
audio_set_module_loop_start(2);     // loop from order 2
audio_set_module_loop_end(8);       // to order 8

// Stop the module
audio_end_module();

// Play a sound sample at a given period (pitch)
// period 428 = middle C for DOS-era SAM files
audio_play_sample("explosion.wav", true, 428);

// Play a PC speaker built-in sound effect (index 0–50)
audio_spot_sample(428, 3);

// Master volume controls
audio_set_music_volume(8);          // module volume
audio_set_sound_volume(8);          // sample volume
audio_set_pcs_volume(8);            // PC speaker volume
audio_set_music_on(1);
audio_set_pcs_on(1);

// Shutdown
quit_audio();
```

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

### Build Libraries with DJGPP

Source: https://github.com/alicelr/megazeux/blob/master/scripts/deps/README.md

Use these commands to build libraries like zlib, libpng, libogg, and libvorbis using the DJGPP toolchain. Ensure the DJGPP bin directory is on your PATH.

```shell
make PLATFORM=djgpp
```

```shell
make PLATFORM=djgpp package
```

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

### Get Absolute Value

Source: https://github.com/alicelr/megazeux/blob/master/docs/WIPHelp.txt

Gives the absolute value of the number n.

```MegaZeux Script
~BABSn
```

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

### Preprocessor Define Constants

Source: https://github.com/alicelr/megazeux/blob/master/docs/STYLE.md

Example of using preprocessor defines for constants in C code.

```c
#define CHAR_W  8
#define CHAR_H  14

```

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

### Configure MegaZeux Build

Source: https://context7.com/alicelr/megazeux/llms.txt

Use `config.sh` to set up the build environment for your target platform. Options include specifying the platform, installation prefix, build type (release, LTO), and enabling features like SDL3 or the network updater.

```bash
./config.sh

```

```bash
./config.sh --platform unix --prefix /usr/local --enable-release --enable-lto

```

```bash
./config.sh --platform mingw64 --prefix scripts/deps/mingw/x64 --enable-release

```

```bash
./config.sh --platform unix --enable-sdl3 --enable-updater

```

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

### Build MinGW Dependencies

Source: https://github.com/alicelr/megazeux/blob/master/scripts/deps/README.md

Use this command to build zlib, libpng, libogg, libvorbis, libSDL, libSDL2, and libSDL3 for MinGW. Ensure MinGW-w64 toolchains are in your PATH.

```makefile
make PLATFORM=mingw
make PLATFORM=mingw package
```

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

### Get String Length

Source: https://github.com/alicelr/megazeux/blob/master/docs/WIPHelp.txt

Retrieves the current length of a string variable. This is a read-only operation.

```RoboticScript
~B$str.length~F
```

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

### Configure MegaZeux with SDL1 Support for PowerPC

Source: https://github.com/alicelr/megazeux/blob/master/arch/darwin/README.md

Configure the build for PowerPC and PowerPC64 architectures, recommending the use of SDL 1.2.

```bash
./config.sh --platform darwin-dist --enable-release --enable-sdl1
```

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

### Prepare Build Directory

Source: https://github.com/alicelr/megazeux/blob/master/BUILDING.md

Prepares a directory for packaging without creating an archive. This is useful for inspecting the build output before archiving.

```makefile
make build
```

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

### Offset and Cap String

Source: https://github.com/alicelr/megazeux/blob/master/docs/WIPHelp.txt

Applies both an offset to the start of the string and a length cap. Useful for extracting substrings.

```RoboticScript
~B$strname+X#Y~F
```

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

### MZV Playback Initialization

Source: https://github.com/alicelr/megazeux/blob/master/contrib/mzvplay/mzvplay.txt

Initializes playback by reading the MZV header and setting up playback parameters.

```MegaZeux Script
: "#play"
set "$mzv_tmp" to "fread4"
if "$mzv_tmp" === "MZXV" then "play"
: "err"
goto "#top"
: "play"
set "local" to "fread_counter"
set "mzv_time_n" to 0
set "mzv_time_d" to 1000
goto "#time"
set "mzv_time_prev" to "mzv_time_n"
set "mzv_w" to 0
set "mzv_h" to 0
set "mzv_vw" to 0
set "mzv_vh" to 0
set "mzv_sp_x" to 0
set "mzv_sp_y" to 0
set "mzv_sp_w" to 1
set "mzv_sp_h" to 1
set "mzv_sp_u" to 0
set "mzv_sp_o" to 0
set "mzv_sp_t" to 0
set "mzv_mode" to 0
set "mzv_fr_n" to 125
set "mzv_fr_d" to 6
set "mzv_fr_adv" to 0
set "$mzv_chr" to ""
set "$mzv_pal" to ""
set "$mzv_idx" to ""
set "$mzv_mzm" to "MZM2"
set "$mzv_mzm.8#4" to 0
set "$mzv_mzm.12#4" to 0
set "$mzv_mzm.13" to 1
: "headers"
goto "#chunk"
goto "head:&$mzv_tmp&"
if "mzv_w" = 0 then "err"
if "mzv_h" = 0 then "err"
set "mzv_vw" to "('mzv_vw' ? 'mzv_vw' : 'mzv_w')"
set "mzv_vh" to "('mzv_vh' ? 'mzv_vh' : 'mzv_h')"
goto "#vlayer"
set "$mzv_mzm.4#2" to "mzv_w"
set "$mzv_mzm.6#2" to "mzv_h"
set "local" to "('mzv_sp_w'*'mzv_sp_h'-1)"
set "local4" to "('mzv_sp_u'o'mzv_vo'o'mzv_sp_o' ? 1 : 0)"
set "local2" to "(('local4' ? -'mzv_w'*8+640/2 : 80-'mzv_w'/2) + 'mzv_sp_x')"
set "local3" to "(('local4' ? -'mzv_h'*14+350/2 : 25-'mzv_h'/2) + 'mzv_sp_y')"
loop start
set "spr&mzv_idx&_width" to "mzv_w"
set "spr&mzv_idx&_height" to "mzv_h"
set "spr&mzv_idx&_refx" to "('loopcount'%'mzv_sp_w'*'mzv_w'+'mzv_vx')"
set "spr&mzv_idx&_refy" to "('loopcount'/'mzv_sp_w'*'mzv_h'+'mzv_vy')"
set "spr&mzv_idx&_vlayer" to 1
set "spr&mzv_idx&_unbound" to "local4"
set "spr&mzv_idx&_offset" to "('loopcount'*'mzv_sp_o'+'mzv_vo')"
set "spr&mzv_idx&_tcol" to "('loopcount' ? 'mzv_sp_t' : -1)"
put c?? Sprite "mzv_idx" at "('loopcount'%'mzv_sp_w'+'local2')" "('loopcount'/'mzv_sp_w'+'local3')"
goto "#sprite"
inc "mzv_idx" by 1
loop for "local"
dec "fread_pos" by 8
: "frames"
goto "#chunk"
goto "frame:&$mzv_tmp&"
. "fallthrough"
: "frame_wait"
dec "mzv_fr_adv" by 1
if "mzv_fr_adv" > 0 then "frames"
: "w"
wait for 1
goto "#frameadv"
if "mzv_fr_adv" > 0 then "frames"
goto "w"
```

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

### Wait for Playback

Source: https://github.com/alicelr/megazeux/blob/master/docs/WIPHelp.txt

Waits for a playback sequence to finish. Typically used after starting music or sound effects.

```MegaZeux Script
#COMMAND2.HLP:_w3:WAIT PLAY [~D!~F]
```

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

### Get Larger of Two Numbers

Source: https://github.com/alicelr/megazeux/blob/master/docs/WIPHelp.txt

Takes the numbers x and y and outputs the larger number. The comma is required.

```MegaZeux Script
~BMAXx,y
```

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

### Configure MegaZeux for Darwin Distribution

Source: https://github.com/alicelr/megazeux/blob/master/arch/darwin/README.md

Use this command to prepare the `darwin-dist` build for release with Link-Time Optimization (LTO).

```bash
./config.sh --platform darwin-dist --enable-release --enable-lto
```