KITAQFC LIBRARY

Test overlap of axis-aligned actor rectangles in world coordinates.

Syntax

unsigned char nes_actor_collide(struct NesActor* a, struct NesActor* b);

Parameters

a

First actor.

b

Second actor.

Return value

Returns 1 for overlap; 0 for separation or edges that merely touch.

Conditions and limits

Use positive widths/heights and keep position+size≤65535. Screen coordinates, attr and flags are ignored.

Usage example

result[3]=nes_actor_collide(&a,&b);nes_actor_set_world(&b,315,95);result[4]=nes_actor_collide(&a,&b);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Project world (300,95) through camera (268,32): red and blue 8×8 parts appear at (32,64) and (40,64). This demonstrates raw OAM Y=63 appearing at 64, and collision changing from zero for touching edges to one for a one-pixel overlap.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_actor.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_actor.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

Test overlap in world coordinates with exclusive right/bottom edges. Keep
position-plus-size sums within u16; touching edges are not collisions.
Require positive widths and heights; zero extents are not rejected before the edge tests.

unsigned char nes_actor_collide(struct NesActor* a, struct NesActor* b)
{
    unsigned short a_right;
    unsigned short b_right;
    unsigned short a_bottom;
    unsigned short b_bottom;

    a_right = (unsigned short)(a->world_x + a->width);
    b_right = (unsigned short)(b->world_x + b->width);
    a_bottom = (unsigned short)(a->world_y + a->height);
    b_bottom = (unsigned short)(b->world_y + b->height);

    if (a_right <= b->world_x)
    {
        return 0;
    }
    if (b_right <= a->world_x)
    {
        return 0;
    }
    if (a_bottom <= b->world_y)
    {
        return 0;
    }
    if (b_bottom <= a->world_y)
    {
        return 0;
    }

    return 1;
}

Write a metasprite into shadow OAM using the actor’s cached screen coordinates.

Syntax

unsigned char nes_actor_draw_metasprite(struct NesActor* actor, unsigned char oam_index, unsigned char* metasprite);

Parameters

actor

Pointer to a writable NesActor.

oam_index

First slot, 0..63; reserve room for every part.

metasprite

Four-byte records dx,dy,tile,attr; dx=255 terminates.

Return value

Returns the next OAM slot index, wrapping at the end of 64 slots.

Conditions and limits

Link runtime.c. The queue copies payloads for a later NMI or safe rendering-off flush. Serialize production against consumption. If a multirow operation runs out of capacity, earlier admitted rows remain queued.

Does not apply the actor’s attr/flags fields. Y is a raw OAM byte, so the visible top is one pixel lower. An OAM DMA is required to display the shadow.

Usage example

result[5]=nes_actor_draw_metasprite(&a,0,parts);result[6]=nes_oam_shadow[3];result[7]=nes_oam_shadow[7];nes_oam_dma(2);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Project world (300,95) through camera (268,32): red and blue 8×8 parts appear at (32,64) and (40,64). This demonstrates raw OAM Y=63 appearing at 64, and collision changing from zero for touching edges to one for a one-pixel overlap.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_actor.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_actor.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

Draw the byte-stream metasprite at cached screen coordinates and return its
next OAM index. Actor attr/flags are not applied by this wrapper.

unsigned char nes_actor_draw_metasprite(struct NesActor* actor, unsigned char oam_index, unsigned char* metasprite)
{
    return nes_metasprite_draw(oam_index, actor->screen_x, actor->screen_y, metasprite);
}

Set an actor’s world X/Y.

Syntax

void nes_actor_set_world(struct NesActor* actor, unsigned short x, unsigned short y);

Parameters

actor

Pointer to a writable NesActor.

x

World X, 0..65535 pixels.

y

World Y, 0..65535 pixels.

Return value

No return value.

Conditions and limits

Does not update screen_x/screen_y. Call update_screen to project through the camera.

Usage example

nes_actor_set_world(&a,300,95);nes_actor_set_world(&b,316,95);result[0]=a.world_x;

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Project world (300,95) through camera (268,32): red and blue 8×8 parts appear at (32,64) and (40,64). This demonstrates raw OAM Y=63 appearing at 64, and collision changing from zero for touching edges to one for a one-pixel overlap.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_actor.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_actor.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

Set the actor's 16-bit world position without updating cached screen coordinates.

void nes_actor_set_world(struct NesActor* actor, unsigned short x, unsigned short y)
{
    actor->world_x = x;
    actor->world_y = y;
}

Subtract camera coordinates from world coordinates and cache the low bytes as screen coordinates.

Syntax

void nes_actor_update_screen(struct NesActor* actor, unsigned short camera_x, unsigned short camera_y);

Parameters

actor

Pointer to a writable NesActor.

camera_x

Camera world X.

camera_y

Camera world Y.

Return value

No return value.

Conditions and limits

Negative or ≥256 results wrap. It does not hide offscreen actors; the game must cull before drawing.

Usage example

nes_actor_update_screen(&a,268,32);result[1]=a.screen_x;result[2]=a.screen_y;

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Project world (300,95) through camera (268,32): red and blue 8×8 parts appear at (32,64) and (40,64). This demonstrates raw OAM Y=63 appearing at 64, and collision changing from zero for touching edges to one for a one-pixel overlap.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_actor.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_actor.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

Subtract the camera and retain only the low coordinate bytes. This performs
wrapping projection, not clipping; callers must hide actors outside the viewport.

void nes_actor_update_screen(struct NesActor* actor, unsigned short camera_x, unsigned short camera_y)
{
    unsigned short dx;
    unsigned short dy;

    dx = (unsigned short)(actor->world_x - camera_x);
    dy = (unsigned short)(actor->world_y - camera_y);

    actor->screen_x = (unsigned char)dx;
    actor->screen_y = (unsigned char)dy;
}

Copy one AssetDesc from the registered table’s ROM bank into caller-provided storage. This retrieves the resource’s metadata, not its payload.

Syntax

u8 asset_get(u8 asset_id, AssetDesc* out_desc);

Parameters

asset_id

Zero-based resource index. A valid ID satisfies asset_id < count for the registered table.

out_desc

Writable storage for one 6-byte descriptor. A null pointer is rejected before accessing the table.

Return value

1 after copying the descriptor; 0 for a null output or an out-of-range ID. On these failures, output storage is unchanged.

Conditions and limits

Register the table before looking up resources. Registration is shared global state: do not change it concurrently with a lookup. The library checks IDs and asset_get’s output pointer, but does not validate the registered table, payload addresses or cartridge contents.

The samples place calling code in fixed bank 0 so source-bank changes cannot unmap the code being executed. These transfers are synchronous. Do not interrupt a transfer with another bank-changing copy or assume the helper makes a whole application interrupt-safe.

Usage example

loaded=asset_get(0,&descriptor);
expect(loaded==1,1);
expect(descriptor.type==ASSET_TYPE_TILES && descriptor.bank==2,2);
expect(descriptor.ptr==asset_shapes && descriptor.len==144,3);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The example reads descriptor 0 and checks its TILES type, bank 2, payload pointer and 144-byte length. Invalid-ID and null-output calls must fail; a failed lookup leaves the previous output value intact.

Expected image: a red row starts at pixel (16,32) and spans 72×8 pixels. It repeats an 8×8 triangle, an 8×8 square outline with a one-pixel border, and a tile with its left four columns filled, three times. The triangle grows from one pixel at the top left to eight pixels on its bottom row.

On FC, a blue triangle and outline at (16,64) show __far_memcpy; a green pair at (16,96) shows asset_load_raw followed by a CHR upload. Each pair occupies 16×8 pixels on a black background. These rows demonstrate copied image bytes, not merely numeric status values.

Expected status: FAILED CHECKS 000 and FIRST FAILURE 00. The verification runs 300 frames and compares text, shape masks and colors against these expectations. This is emulator evidence, not a physical-hardware test.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Copy a descriptor from its ROM bank into caller storage. Null output or an
out-of-range ID returns zero without reading the table.

u8 asset_get(u8 asset_id, AssetDesc* out_desc)
{
    if (out_desc == 0) return 0;
    if (asset_id >= asset_table_count) return 0;
    __far_memcpy((u8*)out_desc, asset_table_bank, (u16)(asset_table + asset_id), sizeof(AssetDesc));
    return 1;
}

Read the resource’s payload-bank number from its descriptor. This is not the bank containing the descriptor table, and the function does not leave the payload bank selected.

Syntax

u8 asset_get_bank(u8 asset_id);

Parameters

asset_id

Zero-based resource index. A valid ID satisfies asset_id < count for the registered table.

Return value

The descriptor’s 8-bit bank, or 0 on lookup failure. Bank zero can also be valid; use asset_get() when success must be distinguished from a zero value.

Conditions and limits

Register the table before looking up resources. Registration is shared global state: do not change it concurrently with a lookup. The library checks IDs and asset_get’s output pointer, but does not validate the registered table, payload addresses or cartridge contents.

Each getter calls asset_get again and copies a descriptor. If you need bank, pointer and length together, call asset_get once and read its fields.

The samples place calling code in fixed bank 0 so source-bank changes cannot unmap the code being executed. These transfers are synchronous. Do not interrupt a transfer with another bank-changing copy or assume the helper makes a whole application interrupt-safe.

Usage example

payload_bank=asset_get_bank(0);
expect(payload_bank==2,17); // Payload bank, not descriptor-table bank 3.
expect(asset_get_bank(4)==0,18); // Failure sentinel; a valid descriptor may also use bank 0.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The example expects payload bank 2 even though the descriptor table is in bank 3. It also checks that an invalid ID returns zero.

Expected image: a red row starts at pixel (16,32) and spans 72×8 pixels. It repeats an 8×8 triangle, an 8×8 square outline with a one-pixel border, and a tile with its left four columns filled, three times. The triangle grows from one pixel at the top left to eight pixels on its bottom row.

On FC, a blue triangle and outline at (16,64) show __far_memcpy; a green pair at (16,96) shows asset_load_raw followed by a CHR upload. Each pair occupies 16×8 pixels on a black background. These rows demonstrate copied image bytes, not merely numeric status values.

Expected status: FAILED CHECKS 000 and FIRST FAILURE 00. The verification runs 300 frames and compares text, shape masks and colors against these expectations. This is emulator evidence, not a physical-hardware test.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Return the asset bank or zero on lookup failure; bank zero may also be valid.

u8 asset_get_bank(u8 asset_id)
{
    AssetDesc desc;
    if (asset_get(asset_id, &desc) == 0) return 0;
    return desc.bank;
}

Read the resource length in bytes from its descriptor. The value is metadata; the function does not inspect the payload or convert bytes to a tile, element or frame count.

Syntax

u16 asset_get_len(u8 asset_id);

Parameters

asset_id

Zero-based resource index. A valid ID satisfies asset_id < count for the registered table.

Return value

The 16-bit len in bytes, or 0 on lookup failure. An empty resource also has length zero; use asset_get() to distinguish the two cases.

Conditions and limits

Register the table before looking up resources. Registration is shared global state: do not change it concurrently with a lookup. The library checks IDs and asset_get’s output pointer, but does not validate the registered table, payload addresses or cartridge contents.

Each getter calls asset_get again and copies a descriptor. If you need bank, pointer and length together, call asset_get once and read its fields.

The samples place calling code in fixed bank 0 so source-bank changes cannot unmap the code being executed. These transfers are synchronous. Do not interrupt a transfer with another bank-changing copy or assume the helper makes a whole application interrupt-safe.

Usage example

expect(asset_get_len(0)==144,21); // Bytes, not tiles.
expect(asset_get_len(3)==0 && asset_get_len(4)==0,22); // Empty asset and invalid ID both yield zero.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The nine-tile resource must report 144 bytes, not nine tiles. Both an empty resource and an invalid ID must report zero.

Expected image: a red row starts at pixel (16,32) and spans 72×8 pixels. It repeats an 8×8 triangle, an 8×8 square outline with a one-pixel border, and a tile with its left four columns filled, three times. The triangle grows from one pixel at the top left to eight pixels on its bottom row.

On FC, a blue triangle and outline at (16,64) show __far_memcpy; a green pair at (16,96) shows asset_load_raw followed by a CHR upload. Each pair occupies 16×8 pixels on a black background. These rows demonstrate copied image bytes, not merely numeric status values.

Expected status: FAILED CHECKS 000 and FIRST FAILURE 00. The verification runs 300 frames and compares text, shape masks and colors against these expectations. This is emulator evidence, not a physical-hardware test.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Return the descriptor byte length, or zero for an invalid ID.

u16 asset_get_len(u8 asset_id)
{
    AssetDesc desc;
    if (asset_get(asset_id, &desc) == 0) return 0;
    return desc.len;
}

Read the 16-bit payload address stored in the descriptor. The returned near pointer carries no bank number. Pair it with asset_get_bank() and a far-copy helper before reading a resource in another ROM bank.

Syntax

const u8* asset_get_ptr(u8 asset_id);

Parameters

asset_id

Zero-based resource index. A valid ID satisfies asset_id < count for the registered table.

Return value

The stored const u8*, or null on lookup failure. The descriptor is not checked for a null payload pointer, so use asset_get() to distinguish lookup failure.

Conditions and limits

Register the table before looking up resources. Registration is shared global state: do not change it concurrently with a lookup. The library checks IDs and asset_get’s output pointer, but does not validate the registered table, payload addresses or cartridge contents.

Each getter calls asset_get again and copies a descriptor. If you need bank, pointer and length together, call asset_get once and read its fields.

The samples place calling code in fixed bank 0 so source-bank changes cannot unmap the code being executed. These transfers are synchronous. Do not interrupt a transfer with another bank-changing copy or assume the helper makes a whole application interrupt-safe.

Usage example

payload_pointer=asset_get_ptr(0);
expect(payload_pointer==asset_shapes,19);
expect(*asset_bank_marker==0xA1,20); // Getting the pointer leaves bank 1 selected.
// Use payload_bank together with payload_pointer for a far copy; do not dereference it here.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The returned pointer must equal the resource’s linked ROM address, while a marker in bank 1 must remain readable. The example then supplies that pointer and payload bank 2 to a far-copy helper.

Expected image: a red row starts at pixel (16,32) and spans 72×8 pixels. It repeats an 8×8 triangle, an 8×8 square outline with a one-pixel border, and a tile with its left four columns filled, three times. The triangle grows from one pixel at the top left to eight pixels on its bottom row.

On FC, a blue triangle and outline at (16,64) show __far_memcpy; a green pair at (16,96) shows asset_load_raw followed by a CHR upload. Each pair occupies 16×8 pixels on a black background. These rows demonstrate copied image bytes, not merely numeric status values.

Expected status: FAILED CHECKS 000 and FIRST FAILURE 00. The verification runs 300 frames and compares text, shape masks and colors against these expectations. This is emulator evidence, not a physical-hardware test.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Return the stored address without switching banks. Pair it with the descriptor
bank before reading banked ROM; a failed lookup returns null.

const u8* asset_get_ptr(u8 asset_id)
{
    AssetDesc desc;
    if (asset_get(asset_id, &desc) == 0) return 0;
    return desc.ptr;
}

Look up a resource and copy min(desc.len, max_len) bytes from its ROM bank to writable memory. The type tag is ignored: tile, map and song data are copied as bytes without decoding or decompression.

Syntax

u8 asset_load_raw(u8 asset_id, void* dst, u16 max_len);

Parameters

asset_id

Zero-based resource index. A valid ID satisfies asset_id < count for the registered table.

dst

Destination in writable memory. Reserve enough space for every byte copied. Except for a zero-byte transfer, a null or invalid destination is not checked.

max_len

Maximum number of bytes to copy, 0–65535. A smaller limit truncates the copy; zero copies no payload bytes.

Return value

0 if lookup fails; otherwise 1, including truncation, a zero limit or an empty resource. The return value is not a byte count and does not indicate that the entire resource fitted.

Conditions and limits

Register the table before looking up resources. Registration is shared global state: do not change it concurrently with a lookup. The library checks IDs and asset_get’s output pointer, but does not validate the registered table, payload addresses or cartridge contents.

Keep the full source range in the intended ROM mapping and the full destination range in writable memory. Copying does not select the next bank at a window boundary, handle overlapping ranges like memmove, or provide VRAM-safe writes. Use the graphics transfer APIs for VRAM.

The samples place calling code in fixed bank 0 so source-bank changes cannot unmap the code being executed. These transfers are synchronous. Do not interrupt a transfer with another bank-changing copy or assume the helper makes a whole application interrupt-safe.

Usage example

loaded=asset_load_raw(0,buffer,7); // Success with truncation: copy seven of 144 bytes.
expect(loaded==1 && buffer[7]==0x55,7);
for(i=0;i<7;i++) expect(buffer[(__safe_index u8)i]==expected_shape_byte(i),8);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

A seven-byte limit copies only the first seven bytes of a 144-byte resource and leaves the next byte at 0x55, yet returns success. The program also checks a full copy, a zero limit, an empty resource and raw copying of a MAP-tagged resource.

Expected image: a red row starts at pixel (16,32) and spans 72×8 pixels. It repeats an 8×8 triangle, an 8×8 square outline with a one-pixel border, and a tile with its left four columns filled, three times. The triangle grows from one pixel at the top left to eight pixels on its bottom row.

On FC, a blue triangle and outline at (16,64) show __far_memcpy; a green pair at (16,96) shows asset_load_raw followed by a CHR upload. Each pair occupies 16×8 pixels on a black background. These rows demonstrate copied image bytes, not merely numeric status values.

Expected status: FAILED CHECKS 000 and FIRST FAILURE 00. The verification runs 300 frames and compares text, shape masks and colors against these expectations. This is emulator evidence, not a physical-hardware test.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Copy the smaller of the asset length and max_len using a bank-aware transfer.
Return one for a valid ID even when the payload is truncated.

u8 asset_load_raw(u8 asset_id, void* dst, u16 max_len)
{
    AssetDesc desc;
    u16 len;
    if (asset_get(asset_id, &desc) == 0) return 0;
    len = desc.len;
    if (len > max_len) len = max_len;
    __far_memcpy((u8*)dst, desc.bank, (u16)desc.ptr, len);
    return 1;
}

Look up a RAW or TILES resource, select its ROM bank and upload all bytes with __vram_write in chunks of at most 128 bytes. Restore the bank saved by bank_get_current() afterwards. Chunking does not wait for another frame.

Syntax

u8 asset_load_tiles(u8 asset_id, u16 vram_dst);

Parameters

asset_id

Zero-based resource index. A valid ID satisfies asset_id < count for the registered table.

vram_dst

PPU byte address, not a CPU address or tile number. Tile-pattern uploads use writable CHR RAM at $0000–$1FFF, with 16 bytes per tile. Keep the whole transfer in the intended PPU region.

Return value

0 for an invalid ID or a type other than RAW/TILES; 1 after an accepted transfer, including a zero-length resource. Success does not validate tile encoding or VRAM visibility.

Conditions and limits

Register the table before looking up resources. Registration is shared global state: do not change it concurrently with a lookup. The library checks IDs and asset_get’s output pointer, but does not validate the registered table, payload addresses or cartridge contents.

The samples place calling code in fixed bank 0 so source-bank changes cannot unmap the code being executed. These transfers are synchronous. Do not interrupt a transfer with another bank-changing copy or assume the helper makes a whole application interrupt-safe.

The upload only writes bytes; it does not place tiles on the map, assign colors or allocate VRAM. Arrange the tile map and palettes separately. The samples upload with rendering disabled and enable the display only after the image is ready.

asset_load_tiles restores bank.c’s software-tracked bank, not a mapper readback. Initialize and maintain that state with bank_switch; direct mapper writes or calls to __bankswitch alone do not update the library’s state. The far-copy intrinsic separately restores the compiler’s bank state.

Use writable CHR RAM for pattern data and keep rendering off for long uploads. If uploading in VBlank, the complete operation must fit the available time; 128-byte chunks do not enforce that limit. This sample uses --mapper=mmc1 --board=surom512. With generic boards, omitting --nes-chr creates blank CHR ROM, not CHR RAM.

Usage example

loaded=asset_load_tiles(0,0x0010); // 144 bytes: library uploads chunks of 128 and 16 bytes.
expect(loaded==1 && bank_get_current()==1 && *asset_bank_marker==0xA1,24);
// LCD and NMI are off; CHR RAM is writable. The library selects payload bank 2 and restores bank 1.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The tile-upload example uses nine original 8×8 patterns, 144 bytes in total. It verifies that MAP and invalid IDs are rejected. On FC, 144 bytes exercise both the 128-byte chunk and the remaining 16 bytes.

Expected image: a red row starts at pixel (16,32) and spans 72×8 pixels. It repeats an 8×8 triangle, an 8×8 square outline with a one-pixel border, and a tile with its left four columns filled, three times. The triangle grows from one pixel at the top left to eight pixels on its bottom row.

On FC, a blue triangle and outline at (16,64) show __far_memcpy; a green pair at (16,96) shows asset_load_raw followed by a CHR upload. Each pair occupies 16×8 pixels on a black background. These rows demonstrate copied image bytes, not merely numeric status values.

Expected status: FAILED CHECKS 000 and FIRST FAILURE 00. The verification runs 300 frames and compares text, shape masks and colors against these expectations. This is emulator evidence, not a physical-hardware test.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Switch to the asset bank, upload tile/raw data in chunks of at most 128 bytes,
then restore the bank recorded by this library. The caller supplies safe PPU timing.

u8 asset_load_tiles(u8 asset_id, u16 vram_dst)
{
    AssetDesc desc;
    const u8* src;
    u16 len;
    u8 chunk;
    u8 old_bank;

    if (asset_get(asset_id, &desc) == 0) return 0;
    if (desc.type != ASSET_TYPE_TILES && desc.type != ASSET_TYPE_RAW) return 0;

    // Restoration uses the library shadow, not a mapper readback; initialize and maintain that shadow.
    old_bank = bank_get_current();
    bank_switch(desc.bank);

    src = desc.ptr;
    len = desc.len;
    // This loop uploads the entire asset synchronously. Chunking does not wait for another frame.
    // Use writable CHR RAM for tile data and keep the source bank visible throughout the transfer.
    while (len != 0) {
        if (len > 128) chunk = 128;
        else chunk = (u8)len;
        __vram_write(vram_dst, src, chunk);
        vram_dst = (u16)(vram_dst + chunk);
        src = src + chunk;
        len = (u16)(len - chunk);
    }

    bank_switch(old_bank);
    return 1;
}

Register the bank, address and entry count of the single active descriptor table. The function stores these three values; it does not copy the table, load any asset or allocate memory.

Syntax

void asset_set_table(u8 bank, const AssetDesc* table, u8 count);

Parameters

bank

8-bit ROM bank containing the descriptor table, not the payload.

table

Near pointer to count consecutive AssetDesc entries. Keep all count * 6 bytes readable in the selected table bank for as long as the table is registered.

count

Number of entries, 0–255. Zero makes every ID invalid; asset_set_table(0, 0, 0) safely registers an empty table.

Return value

None (void).

Conditions and limits

Register the table before looking up resources. Registration is shared global state: do not change it concurrently with a lookup. The library checks IDs and asset_get’s output pointer, but does not validate the registered table, payload addresses or cartridge contents.

Usage example

asset_set_table(3,asset_descriptors,4); // Four descriptors in bank 3, payloads in bank 2.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This example registers four descriptors in bank 3 whose nonempty payloads are in bank 2. It also registers an empty table and verifies that lookup fails without reading address zero.

Expected image: a red row starts at pixel (16,32) and spans 72×8 pixels. It repeats an 8×8 triangle, an 8×8 square outline with a one-pixel border, and a tile with its left four columns filled, three times. The triangle grows from one pixel at the top left to eight pixels on its bottom row.

On FC, a blue triangle and outline at (16,64) show __far_memcpy; a green pair at (16,96) shows asset_load_raw followed by a CHR upload. Each pair occupies 16×8 pixels on a black background. These rows demonstrate copied image bytes, not merely numeric status values.

Expected status: FAILED CHECKS 000 and FIRST FAILURE 00. The verification runs 300 frames and compares text, shape masks and colors against these expectations. This is emulator evidence, not a physical-hardware test.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Retain a bank-qualified descriptor table; the caller keeps its storage valid.

void asset_set_table(u8 bank, const AssetDesc* table, u8 count)
{
    asset_table_bank = bank;
    asset_table = table;
    asset_table_count = count;
}

Copy rows of attribute bytes covering a tile rectangle into the queue.

Syntax

unsigned char nes_attr_queue_rect(unsigned short nt_base, unsigned char tile_x, unsigned char tile_y, unsigned char width, unsigned char height);

Parameters

nt_base

Logical nametable base $2000/$2400/$2800/$2C00; mirroring determines physical independence.

tile_x

Left tile column, visible range 0..31.

tile_y

Top tile row, visible range 0..29.

width

Width in tiles.

height

Height in tiles.

Return value

Returns 1 for complete admission or an empty rectangle, 0 for invalid bounds or insufficient capacity. Invalid bounds enqueue nothing.

Conditions and limits

The shared 64-byte attribute shadow occupies CPU RAM $03E0..$041F. Reserve that range. One attribute byte covers 4×4 tiles; each two-bit field selects a palette for a 2×2-tile quadrant.

Link runtime.c. The queue copies payloads for a later NMI or safe rendering-off flush. Serialize production against consumption. If a multirow operation runs out of capacity, earlier admitted rows remain queued.

An attribute byte covers 4×4 tiles. Whole intersecting bytes are transferred, so preserve correct neighboring quadrant values in the shadow.

Usage example

result[5]=nes_attr_queue_rect(0x2000,2,4,4,4);result[6]=nes_vram_queue_used;result[7]=nes_attr_queue_rect(0x2000,10,4,4,4);result[8]=nes_attr_queue_rect(0x2000,30,28,2,2);nes_vram_queue_nmi_flush();

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Learn rectangular attribute uploads: red 32×32 at (16,32), blue 32×32 at (80,32), green 16×16 at bottom-right (240,224). The example preserves adjacent quadrants and reaches the final attribute byte correctly.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_attributes.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_attributes.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

Queue the attribute bytes covering a tile rectangle within 32x30 tiles.
Empty rectangles succeed; invalid bounds fail without queuing.
Capacity failure may leave earlier rows queued.

unsigned char nes_attr_queue_rect(unsigned short nt_base, unsigned char tile_x, unsigned char tile_y, unsigned char width, unsigned char height)
{
    unsigned char qx0;
    unsigned char qy0;
    unsigned char qx1;
    unsigned char qy1;
    unsigned char row;
    unsigned char col;
    // The runtime queue copies these local bytes before return; they are not retained pointers.
    // Caller coordinates must keep each computed row length within eight bytes.
    unsigned char line[8];
    unsigned short ppu_addr;
    unsigned char len;

    if (width == 0 || height == 0) return 1;
    if (tile_x >= 32 || tile_y >= 30) return 0;
    if (width > (unsigned char)(32 - tile_x) || height > (unsigned char)(30 - tile_y)) return 0;

    qx0 = (unsigned char)(tile_x >> 2);
    qy0 = (unsigned char)(tile_y >> 2);
    qx1 = (unsigned char)((tile_x + width - 1) >> 2);
    qy1 = (unsigned char)((tile_y + height - 1) >> 2);

    row = qy0;
    while (1)
    {
        len = (unsigned char)(qx1 - qx0 + 1);
        col = 0;
        while (col != len)
        {
            line[col] = nes_attr_shadow[(unsigned char)(row * 8 + qx0 + col)];
            col = (unsigned char)(col + 1);
        }
        ppu_addr = (unsigned short)(nes_attr_base_from_nt(nt_base) + (unsigned short)(row * 8 + qx0));
        if (nes_vram_queue_try_write(ppu_addr, line, len) == 0)
        {
            return 0;
        }
        if (row == qy1)
        {
            break;
        }
        row = (unsigned char)(row + 1);
    }
    return 1;
}

Copy 64 already-packed attribute bytes into the shared shadow.

Syntax

void nes_attr_shadow_build_from_palette_map(unsigned char* src64);

Parameters

src64

Readable 64-byte packed attribute table, not an array of per-tile palette IDs.

Return value

No return value.

Conditions and limits

The shared 64-byte attribute shadow occupies CPU RAM $03E0..$041F. Reserve that range. One attribute byte covers 4×4 tiles; each two-bit field selects a palette for a 2×2-tile quadrant.

Usage example

for(i=0;i<64;i++)table[i]=0;table[0]=0xE4;nes_attr_shadow_build_from_palette_map(table);result[0]=nes_attr_shadow[0];

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Learn rectangular attribute uploads: red 32×32 at (16,32), blue 32×32 at (80,32), green 16×16 at bottom-right (240,224). The example preserves adjacent quadrants and reaches the final attribute byte correctly.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_attributes.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_attributes.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

KITAQFC phase15 attribute patch helpers.


Copy 64 already-packed attribute bytes into shadow storage. This does not
convert one palette ID per tile into NES attribute bitfields.
The source must expose all 64 packed bytes and stay readable for the duration of this copy.

void nes_attr_shadow_build_from_palette_map(unsigned char* src64)
{
    unsigned char i;
    i = 0;
    while (i != 64)
    {
        nes_attr_shadow[i] = (unsigned char)(src64[i] & 0xFF);
        i = (unsigned char)(i + 1);
    }
}

Replace the palette fields of every 2×2-tile quadrant touched by a rectangle.

Syntax

void nes_attr_shadow_fill_rect(unsigned char tile_x, unsigned char tile_y, unsigned char width, unsigned char height, unsigned char pal_index);

Parameters

tile_x

Left tile column, visible range 0..31.

tile_y

Top tile row, visible range 0..29.

width

Width in tiles.

height

Height in tiles.

pal_index

Palette index; only the low two bits are used.

Return value

No return value.

Conditions and limits

The shared 64-byte attribute shadow occupies CPU RAM $03E0..$041F. Reserve that range. One attribute byte covers 4×4 tiles; each two-bit field selects a palette for a 2×2-tile quadrant.

Keep the entire rectangle within 32×30 tiles. Empty or invalid rectangles change nothing. Odd boundaries expand to quadrant boundaries, so neighboring tiles outside the rectangle can share the new palette.

Usage example

nes_attr_shadow_fill_rect(2,4,4,4,1);nes_attr_shadow_fill_rect(10,4,4,4,2);nes_attr_shadow_fill_rect(30,28,2,2,3);result[1]=nes_attr_shadow[8];result[2]=nes_attr_shadow[9];result[3]=nes_attr_shadow[15];result[4]=nes_attr_shadow[63];

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Learn rectangular attribute uploads: red 32×32 at (16,32), blue 32×32 at (80,32), green 16×16 at bottom-right (240,224). The example preserves adjacent quadrants and reaches the final attribute byte correctly.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_attributes.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_attributes.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

Apply a palette to every two-by-two tile quadrant touched by the rectangle.
Empty or out-of-range rectangles leave the shadow unchanged.

void nes_attr_shadow_fill_rect(unsigned char tile_x, unsigned char tile_y, unsigned char width, unsigned char height, unsigned char pal_index)
{
    unsigned char qx0;
    unsigned char qy0;
    unsigned char qx1;
    unsigned char qy1;
    unsigned char qx;
    unsigned char qy;

    if (width == 0 || height == 0) return;
    if (tile_x >= 32 || tile_y >= 30) return;
    if (width > (unsigned char)(32 - tile_x) || height > (unsigned char)(30 - tile_y)) return;

    qx0 = nes_attr_rect_left(tile_x);
    qy0 = nes_attr_rect_top(tile_y);
    qx1 = nes_attr_rect_left((unsigned char)(tile_x + width - 1));
    qy1 = nes_attr_rect_top((unsigned char)(tile_y + height - 1));

    qy = qy0;
    while (1)
    {
        qx = qx0;
        while (1)
        {
            nes_attr_shadow_set_quad((unsigned char)(qx << 1), (unsigned char)(qy << 1), pal_index);
            if (qx == qx1)
            {
                break;
            }
            qx = (unsigned char)(qx + 1);
        }
        if (qy == qy1)
        {
            break;
        }
        qy = (unsigned char)(qy + 1);
    }
}

Replace the enable state of all five APU channels with the supplied mask.

Syntax

void nes_apu_channel_enable(u8 mask);

Parameters

mask

Complete APU_STATUS enable mask. Bits 0..4 select pulse1, pulse2, triangle, noise and DMC; upper bits are discarded.

Return value

No return value. Changes sound registers or driver state.

Usage example

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

Expected result

Hear pulse1, pulse2, triangle, noise, tick and move. Timer 253 gives roughly 440 Hz pulses and 220 Hz triangle under NTSC. Tick is about 111 Hz; move is about 174 Hz and ends sooner. The final interval is silent.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Replace all five channel-enable bits in APU_STATUS; this is not an additive enable.

void nes_apu_channel_enable(u8 mask)
{
    APU_STATUS = (u8)(mask & 0x1F);
}

Disable frame IRQ, enable four voices and install quiet controls. DMC remains disabled.

Syntax

void nes_apu_init(void);

Return value

No return value. Changes sound registers or driver state.

Usage example

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

Expected result

Hear pulse1, pulse2, triangle, noise, tick and move. Timer 253 gives roughly 440 Hz pulses and 220 Hz triangle under NTSC. Tick is about 111 Hz; move is about 174 Hz and ends sooner. The final interval is silent.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Disable frame IRQs, enable the four tonal/noise channels and install quiet
control defaults. DMC remains disabled.

void nes_apu_init(void)
{
    APU_FRAME = 0x40;
    APU_STATUS = 0x0F;
    SQ1_VOL = 0x10;
    SQ1_SWEEP = 0x08;
    SQ2_VOL = 0x10;
    SQ2_SWEEP = 0x08;
    TRI_LINEAR = 0x80;
    NOISE_VOL = 0x10;
    DMC_FREQ = 0x00;
    DMC_RAW = 0x00;
}

Disable all channels and clear pulse/noise volume and DMC output.

Syntax

void nes_apu_silence_all(void);

Return value

No return value. Changes sound registers or driver state.

Usage example

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

Expected result

Hear pulse1, pulse2, triangle, noise, tick and move. Timer 253 gives roughly 440 Hz pulses and 220 Hz triangle under NTSC. Tick is about 111 Hz; move is about 174 Hz and ends sooner. The final interval is silent.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Disable every channel and clear volume/DMC output settings used by this helper.

void nes_apu_silence_all(void)
{
    APU_STATUS = 0x00;
    SQ1_VOL = 0x10;
    SQ2_VOL = 0x10;
    TRI_LINEAR = 0x80;
    NOISE_VOL = 0x10;
    DMC_FREQ = 0x00;
    DMC_RAW = 0x00;
}

Configure DMC control/output and convert its sample address and length into register units.

Syntax

void nes_dmc_config(u8 flags_rate, u8 output_level, u16 sample_addr, u16 sample_len);

Parameters

flags_rate

DMC bit 7 IRQ, bit 6 looping, low nibble rate index. The sample does not enable IRQ.

output_level

Initial DMC output counter, 0..127; only the low seven bits are written.

sample_addr

DMC data CPU address: a 64-byte boundary in $C000..$FFC0.

sample_len

Byte length 16*n+1 in 1..4081. Do not pass zero or an unrepresentable length.

Return value

No return value. Changes sound registers or driver state.

Conditions and limits

DMC reads ROM from a 64-byte boundary in $C000..$FFC0. Length is 16*n+1 bytes, 1..4081. These helpers neither validate alignment/ranges nor switch banks. The sample puts original data in fixed bank 0 with __aligned(64) and checks its placement at runtime.

Usage example

// A 17-byte original delta pattern, aligned to a 64-byte DMC start boundary.
#include "fc_sound_example.h"
#pragma bank 0
__aligned(64) __prg_rom u8 delta[17]={0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xAA};
void main(void) {
    sound_begin("DMC ORIGINAL DELTAS");
    sound_result[0]=(u8)(((u16)delta&63)==0);
    sound_result[1]=(u8)((u16)delta>=0xC000);
    // Loop at NTSC rate index 10; start the output accumulator at its midpoint.
    nes_dmc_config(0x4A,64,(u16)delta,17);
    nes_dmc_start();
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    nes_dmc_play(0x4C,64,(u16)delta,17);
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    sound_end();
}

Expected result

An original delta pattern plays at rate 10, pauses, then plays faster at rate 12. DMC stop retains its output counter, so the gap may contain a transient. The final operation silences the whole APU.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_dmc.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-dmc.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Convert a CPU sample address and byte length to DMC register units. Supply
an address in 0xC000-0xFFC0 aligned to 64 bytes and a representable length
16*n+1 in 1..4081; inputs are narrowed without validation or bank management.

void nes_dmc_config(u8 flags_rate, u8 output_level, u16 sample_addr, u16 sample_len)
{
    DMC_FREQ = flags_rate;
    DMC_RAW = (u8)(output_level & 0x7F);
    // Keep the sample bytes mapped at these CPU addresses during playback; this does not select a ROM bank.
    DMC_START = (u8)((sample_addr - 0xC000) >> 6);
    DMC_LEN = (u8)((sample_len - 1) >> 4);
}

Configure the DMC sample and immediately start playback.

Syntax

void nes_dmc_play(u8 flags_rate, u8 output_level, u16 sample_addr, u16 sample_len);

Parameters

flags_rate

DMC bit 7 IRQ, bit 6 looping, low nibble rate index. The sample does not enable IRQ.

output_level

Initial DMC output counter, 0..127; only the low seven bits are written.

sample_addr

DMC data CPU address: a 64-byte boundary in $C000..$FFC0.

sample_len

Byte length 16*n+1 in 1..4081. Do not pass zero or an unrepresentable length.

Return value

No return value. Changes sound registers or driver state.

Conditions and limits

DMC reads ROM from a 64-byte boundary in $C000..$FFC0. Length is 16*n+1 bytes, 1..4081. These helpers neither validate alignment/ranges nor switch banks. The sample puts original data in fixed bank 0 with __aligned(64) and checks its placement at runtime.

Usage example

// A 17-byte original delta pattern, aligned to a 64-byte DMC start boundary.
#include "fc_sound_example.h"
#pragma bank 0
__aligned(64) __prg_rom u8 delta[17]={0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xAA};
void main(void) {
    sound_begin("DMC ORIGINAL DELTAS");
    sound_result[0]=(u8)(((u16)delta&63)==0);
    sound_result[1]=(u8)((u16)delta>=0xC000);
    // Loop at NTSC rate index 10; start the output accumulator at its midpoint.
    nes_dmc_config(0x4A,64,(u16)delta,17);
    nes_dmc_start();
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    nes_dmc_play(0x4C,64,(u16)delta,17);
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    sound_end();
}

Expected result

An original delta pattern plays at rate 10, pauses, then plays faster at rate 12. DMC stop retains its output counter, so the gap may contain a transient. The final operation silences the whole APU.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_dmc.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-dmc.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Install sample parameters, then start DMC using the full-channel enable mask.

void nes_dmc_play(u8 flags_rate, u8 output_level, u16 sample_addr, u16 sample_len)
{
    nes_dmc_config(flags_rate, output_level, sample_addr, sample_len);
    nes_dmc_start();
}

Write APU_STATUS=0x1F, enabling DMC and all four other voices.

Syntax

void nes_dmc_start(void);

Return value

No return value. Changes sound registers or driver state.

Conditions and limits

DMC reads ROM from a 64-byte boundary in $C000..$FFC0. Length is 16*n+1 bytes, 1..4081. These helpers neither validate alignment/ranges nor switch banks. The sample puts original data in fixed bank 0 with __aligned(64) and checks its placement at runtime.

Usage example

// A 17-byte original delta pattern, aligned to a 64-byte DMC start boundary.
#include "fc_sound_example.h"
#pragma bank 0
__aligned(64) __prg_rom u8 delta[17]={0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xAA};
void main(void) {
    sound_begin("DMC ORIGINAL DELTAS");
    sound_result[0]=(u8)(((u16)delta&63)==0);
    sound_result[1]=(u8)((u16)delta>=0xC000);
    // Loop at NTSC rate index 10; start the output accumulator at its midpoint.
    nes_dmc_config(0x4A,64,(u16)delta,17);
    nes_dmc_start();
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    nes_dmc_play(0x4C,64,(u16)delta,17);
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    sound_end();
}

Expected result

An original delta pattern plays at rate 10, pauses, then plays faster at rate 12. DMC stop retains its output counter, so the gap may contain a transient. The final operation silences the whole APU.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_dmc.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-dmc.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Enable DMC together with all four other channels by replacing the status mask.

void nes_dmc_start(void)
{
    APU_STATUS = 0x1F;
}

Write APU_STATUS=0x0F, stopping DMC while setting all four other voice-enable bits.

Syntax

void nes_dmc_stop(void);

Return value

No return value. Changes sound registers or driver state.

Conditions and limits

DMC reads ROM from a 64-byte boundary in $C000..$FFC0. Length is 16*n+1 bytes, 1..4081. These helpers neither validate alignment/ranges nor switch banks. The sample puts original data in fixed bank 0 with __aligned(64) and checks its placement at runtime.

Usage example

// A 17-byte original delta pattern, aligned to a 64-byte DMC start boundary.
#include "fc_sound_example.h"
#pragma bank 0
__aligned(64) __prg_rom u8 delta[17]={0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xAA};
void main(void) {
    sound_begin("DMC ORIGINAL DELTAS");
    sound_result[0]=(u8)(((u16)delta&63)==0);
    sound_result[1]=(u8)((u16)delta>=0xC000);
    // Loop at NTSC rate index 10; start the output accumulator at its midpoint.
    nes_dmc_config(0x4A,64,(u16)delta,17);
    nes_dmc_start();
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    nes_dmc_play(0x4C,64,(u16)delta,17);
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    sound_end();
}

Expected result

An original delta pattern plays at rate 10, pauses, then plays faster at rate 12. DMC stop retains its output counter, so the gap may contain a transient. The final operation silences the whole APU.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_dmc.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-dmc.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Disable DMC while leaving all four other channel-enable bits set.

void nes_dmc_stop(void)
{
    APU_STATUS = 0x0F;
}

Trigger pulse 1 with control 0x5A, timer 0x0280 and length index 2 for a higher, shorter movement blip.

Syntax

void nes_sfx_move_blip(void);

Return value

No return value. Changes sound registers or driver state.

Conditions and limits

This helper writes a single-channel APU_STATUS mask, disabling other voices. It is not a multivoice mixer. For pulse/triangle voices, period is a timer value: smaller values give higher pitches. Sample pitches and durations were checked with NTSC timing.

Usage example

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

Expected result

Hear pulse1, pulse2, triangle, noise, tick and move. Timer 253 gives roughly 440 Hz pulses and 220 Hz triangle under NTSC. Tick is about 111 Hz; move is about 174 Hz and ends sooner. The final interval is silent.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Trigger the predefined pulse-1 movement effect.

void nes_sfx_move_blip(void)
{
    nes_sfx_square1(0x5A, 0x0280, 2);
}

Enable only noise and write envelope, period/mode and length index.

Syntax

void nes_sfx_noise(u8 volume, u8 period_mode, u8 length_index);

Parameters

volume

Raw noise control: bit 5 length halt, bit 4 constant volume, low nibble volume or envelope period.

period_mode

Noise register: bit 7 short mode, low nibble period-table index.

length_index

Length-table index 0..31, not a frame count. Only the low five bits reach the register.

Return value

No return value. Changes sound registers or driver state.

Conditions and limits

This helper writes a single-channel APU_STATUS mask, disabling other voices. It is not a multivoice mixer. For pulse/triangle voices, period is a timer value: smaller values give higher pitches. Sample pitches and durations were checked with NTSC timing.

Usage example

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

Expected result

Hear pulse1, pulse2, triangle, noise, tick and move. Timer 253 gives roughly 440 Hz pulses and 220 Hz triangle under NTSC. Tick is about 111 Hz; move is about 174 Hz and ends sooner. The final interval is silent.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Enable only noise and load envelope/control, period/mode and length fields.

void nes_sfx_noise(u8 volume, u8 period_mode, u8 length_index)
{
    APU_STATUS = 0x08;
    NOISE_VOL = volume;
    NOISE_LO = period_mode;
    NOISE_HI = (u8)(length_index << 3);
}

Enable only pulse 1, disable sweep and write control, timer and length index.

Syntax

void nes_sfx_square1(u8 duty_volume, u16 period, u8 length_index);

Parameters

duty_volume

Raw pulse control: bits 7..6 duty, bit 5 length halt, bit 4 constant volume, low nibble volume or envelope period.

period

11-bit timer 0..2047. Pulse frequency is CPU clock/[16*(period+1)]; triangle is CPU clock/[32*(period+1)].

length_index

Length-table index 0..31, not a frame count. Only the low five bits reach the register.

Return value

No return value. Changes sound registers or driver state.

Conditions and limits

This helper writes a single-channel APU_STATUS mask, disabling other voices. It is not a multivoice mixer. For pulse/triangle voices, period is a timer value: smaller values give higher pitches. Sample pitches and durations were checked with NTSC timing.

Usage example

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

Expected result

Hear pulse1, pulse2, triangle, noise, tick and move. Timer 253 gives roughly 440 Hz pulses and 220 Hz triangle under NTSC. Tick is about 111 Hz; move is about 174 Hz and ends sooner. The final interval is silent.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Enable only pulse 1, disable its sweep and load control, 11-bit timer and
length-table index. Starting this effect disables the other APU channels.

void nes_sfx_square1(u8 duty_volume, u16 period, u8 length_index)
{
    APU_STATUS = 0x01;
    SQ1_SWEEP = 0x08;
    SQ1_VOL = duty_volume;
    SQ1_LO = (u8)period;
    // Only the low five length-index bits and low eleven timer bits reach the registers.
    SQ1_HI = (u8)((u8)(length_index << 3) | (u8)((period >> 8) & 0x07));
}

Enable only pulse 2, disable sweep and write control, timer and length index.

Syntax

void nes_sfx_square2(u8 duty_volume, u16 period, u8 length_index);

Parameters

duty_volume

Raw pulse control: bits 7..6 duty, bit 5 length halt, bit 4 constant volume, low nibble volume or envelope period.

period

11-bit timer 0..2047. Pulse frequency is CPU clock/[16*(period+1)]; triangle is CPU clock/[32*(period+1)].

length_index

Length-table index 0..31, not a frame count. Only the low five bits reach the register.

Return value

No return value. Changes sound registers or driver state.

Conditions and limits

This helper writes a single-channel APU_STATUS mask, disabling other voices. It is not a multivoice mixer. For pulse/triangle voices, period is a timer value: smaller values give higher pitches. Sample pitches and durations were checked with NTSC timing.

Usage example

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

Expected result

Hear pulse1, pulse2, triangle, noise, tick and move. Timer 253 gives roughly 440 Hz pulses and 220 Hz triangle under NTSC. Tick is about 111 Hz; move is about 174 Hz and ends sooner. The final interval is silent.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Enable only pulse 2 and load its control/timer/length fields, disabling other channels.

void nes_sfx_square2(u8 duty_volume, u16 period, u8 length_index)
{
    APU_STATUS = 0x02;
    SQ2_SWEEP = 0x08;
    SQ2_VOL = duty_volume;
    SQ2_LO = (u8)period;
    SQ2_HI = (u8)((u8)(length_index << 3) | (u8)((period >> 8) & 0x07));
}

Trigger pulse 1 with control 0x9A, timer 0x03F0 and length index 4 for a short low tick.

Syntax

void nes_sfx_tick_blip(void);

Return value

No return value. Changes sound registers or driver state.

Conditions and limits

This helper writes a single-channel APU_STATUS mask, disabling other voices. It is not a multivoice mixer. For pulse/triangle voices, period is a timer value: smaller values give higher pitches. Sample pitches and durations were checked with NTSC timing.

Usage example

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

Expected result

Hear pulse1, pulse2, triangle, noise, tick and move. Timer 253 gives roughly 440 Hz pulses and 220 Hz triangle under NTSC. Tick is about 111 Hz; move is about 174 Hz and ends sooner. The final interval is silent.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Trigger the predefined pulse-1 tick effect; it inherits the exclusive-channel behavior.

void nes_sfx_tick_blip(void)
{
    nes_sfx_square1(0x9A, 0x03F0, 4);
}

Enable only triangle and write linear counter, timer and length index.

Syntax

void nes_sfx_triangle(u8 linear, u16 period, u8 length_index);

Parameters

linear

Triangle linear counter: bit 7 control/length halt, low seven bits reload value.

period

11-bit timer 0..2047. Pulse frequency is CPU clock/[16*(period+1)]; triangle is CPU clock/[32*(period+1)].

length_index

Length-table index 0..31, not a frame count. Only the low five bits reach the register.

Return value

No return value. Changes sound registers or driver state.

Conditions and limits

This helper writes a single-channel APU_STATUS mask, disabling other voices. It is not a multivoice mixer. For pulse/triangle voices, period is a timer value: smaller values give higher pitches. Sample pitches and durations were checked with NTSC timing.

Usage example

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

Expected result

Hear pulse1, pulse2, triangle, noise, tick and move. Timer 253 gives roughly 440 Hz pulses and 220 Hz triangle under NTSC. Tick is about 111 Hz; move is about 174 Hz and ends sooner. The final interval is silent.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Enable only triangle and load linear-counter, timer and length fields.

void nes_sfx_triangle(u8 linear, u16 period, u8 length_index)
{
    APU_STATUS = 0x04;
    TRI_LINEAR = linear;
    TRI_LO = (u8)period;
    TRI_HI = (u8)((u8)(length_index << 3) | (u8)((period >> 8) & 0x07));
}

Return the last bank number stored by bank_switch. This reads software bookkeeping, not cartridge registers.

Syntax

u8 bank_get_current(void);

Return value

The u8 value most recently stored by bank_switch; zero before initialization.

Conditions and limits

The library record starts at zero and does not discover the cartridge's startup mapping. Initialize it with bank_switch. Direct intrinsics and raw mapper writes do not update this separate record; bank_get_current therefore cannot verify the actual hardware mapping.

Usage example

starting_bank=bank_get_current(); // Last value recorded by bank_switch.
bank_expect(starting_bank==2,1);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The initial bank_switch(2) records and selects bank 2. Later, direct switching selects bank 1 and reads A1 from home1 while bank_get_current still reports 2; switching back makes home2 read B2 again.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 02: the far_call macro and __farcall each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Read this wrapper's bank shadow; arbitrary mapper writes do not update it.

u8 bank_get_current(void)
{
    return kq_bank_current;
}

Record the requested bank in the library, then select it through the compiler's mapper-specific PRG-bank helper.

Syntax

void bank_switch(u8 bank);

Parameters

bank

An unsigned 8-bit ROM-bank number. For a call, it must agree with the function's placement; for a read, it selects the source mapping. Use the target cartridge's valid range.

Return value

None (void).

Conditions and limits

A permanent bank change must not unmap the executing code or its return address. Put this call, bank_switch itself when used, and the code that continues afterwards in common/fixed bank 0, as the sample does.

The library record starts at zero and does not discover the cartridge's startup mapping. Initialize it with bank_switch. Direct intrinsics and raw mapper writes do not update this separate record; bank_get_current therefore cannot verify the actual hardware mapping.

FC switch-bank numbers are logical compiler numbers. Zero denotes common ROM, not a switch target. The helper normalizes zero to bank 1. On SUROM512, only 1–30 are valid: an out-of-range constant passed directly to the switching intrinsic is a build error; an invalid runtime value falls back to 1 and sets the mapper-fault state. Read common ROM directly instead of requesting a bank-zero switch.

Usage example

bank_switch(2); // Select the payload window and update library bookkeeping.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The initial bank_switch(2) records and selects bank 2. Later, direct switching selects bank 1 and reads A1 from home1 while bank_get_current still reports 2; switching back makes home2 read B2 again.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 02: the far_call macro and __farcall each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Record the bank in the library shadow and invoke the mapper-aware compiler intrinsic.

void bank_switch(u8 bank)
{
    kq_bank_current = bank;
    __bankswitch(bank);
}

Expand to __farcall((bank), func). This macro keeps the target as a function name visible to the compiler; it is not an indirect callback-pointer call.

Syntax

#define far_call(bank, func) __farcall((bank), func)

Parameters

bank

An unsigned 8-bit ROM-bank number. For a call, it must agree with the function's placement; for a read, it selects the source mapping. Use the target cartridge's valid range.

func

The declared name of a function with no parameters. A variable holding a function address is not accepted by this named-call intrinsic. The bank argument is not forwarded as a callback parameter.

Return value

The called function's result type determines the result. A void callback yields no value; u8 and u16 callbacks return their scalar value. The displayed sample uses void callbacks.

Conditions and limits

These calls do not forward user arguments or make the callback interrupt-reentrant. Keep the callback's own data, stack and interrupt use valid. The bank-restoring call paths are tested with nested calls and repeated calls; physical hardware and arbitrary interrupt interleavings are not covered by this example.

FC switch-bank numbers are logical compiler numbers. Zero denotes common ROM, not a switch target. The helper normalizes zero to bank 1. On SUROM512, only 1–30 are valid: an out-of-range constant passed directly to the switching intrinsic is a build error; an invalid runtime value falls back to 1 and sets the mapper-fault state. Read common ROM directly instead of requesting a bank-zero switch.

Usage example

far_call(3,callback); // No arguments; callback reads payload[0] in bank 3.
bank_expect(callback_count==1 && callback_byte==0xD3,15);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

At this point in the complete program, far_call raises callback_count to 1. The callback reads D3 from bank 3. A later near read of B2 from home2 verifies that execution returned with bank 2 mapped.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 02: the far_call macro and __farcall each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Copy len bytes from the specified ROM bank into caller-owned RAM through the far-memory intrinsic. Restore the previous bank before returning.

Syntax

void far_data_read(u8 bank, const void* addr, void* dst, u16 len);

Parameters

bank

An unsigned 8-bit ROM-bank number. For a call, it must agree with the function's placement; for a read, it selects the source mapping. Use the target cartridge's valid range.

addr

Near pointer to readable source bytes in the selected ROM bank. It does not contain a bank number.

dst

Destination in writable memory. Reserve enough space for every byte copied. Except for a zero-byte transfer, a null or invalid destination is not checked.

len

Byte count, 0–65535. Zero performs no memory copy, but the bank-selection and restoration steps still run.

Return value

None (void).

Conditions and limits

Keep the full source range in the intended ROM mapping and the full destination range in writable memory. Copying does not select the next bank at a window boundary, handle overlapping ranges like memmove, or provide VRAM-safe writes. Use the graphics transfer APIs for VRAM.

Far reads and copies are synchronous and use shared compiler scratch. Do not let an interrupt run another banked transfer over the same scratch while one is active. On GB, the copy helper also uses one shared HRAM slot for the saved bank. The sample performs these operations from fixed code with no competing banked-transfer handler.

FC switch-bank numbers are logical compiler numbers. Zero denotes common ROM, not a switch target. The helper normalizes zero to bank 1. On SUROM512, only 1–30 are valid: an out-of-range constant passed directly to the switching intrinsic is a build error; an invalid runtime value falls back to 1 and sets the mapper-fault state. Read common ROM directly instead of requesting a bank-zero switch.

Usage example

far_data_read(3,payload,buffer,4); // Copy into four writable RAM bytes.
bank_expect(buffer[0]==0xD3 && buffer[1]==0x7A && buffer[2]==0x5C && buffer[3]==0x96,7);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This excerpt copies 4 bytes through far_data_read and checks the buffer against D3 7A 5C 96. The source descriptor or pointer is retained by the caller; the full program separately checks a zero-length copy and bank restoration.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 02: the far_call macro and __farcall each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Copy len bytes from banked ROM to caller-owned writable storage.

void far_data_read(u8 bank, const void* addr, void* dst, u16 len)
{
    __far_memcpy((u8*)dst, bank, (u16)addr, len);
}

Read two consecutive bytes through __farpeek16 and combine them as a little-endian word. The first byte becomes the low eight bits.

Syntax

u16 far_data_read16(u8 bank, const void* addr);

Parameters

bank

An unsigned 8-bit ROM-bank number. For a call, it must agree with the function's placement; for a read, it selects the source mapping. Use the target cartridge's valid range.

addr

Near pointer to readable source bytes in the selected ROM bank. It does not contain a bank number.

Return value

The little-endian word read, as u16 (0–65535).

Conditions and limits

The complete byte or word must be readable in the selected CPU mapping. These reads do not validate pointers, clip addresses or advance automatically to another ROM bank at a window boundary. A word read needs two valid consecutive bytes.

Far reads and copies are synchronous and use shared compiler scratch. Do not let an interrupt run another banked transfer over the same scratch while one is active. On GB, the copy helper also uses one shared HRAM slot for the saved bank. The sample performs these operations from fixed code with no competing banked-transfer handler.

FC switch-bank numbers are logical compiler numbers. Zero denotes common ROM, not a switch target. The helper normalizes zero to bank 1. On SUROM512, only 1–30 are valid: an out-of-range constant passed directly to the switching intrinsic is a build error; an invalid runtime value falls back to 1 and sets the mapper-fault state. Read common ROM directly instead of requesting a bank-zero switch.

Usage example

word_value=far_data_read16(3,payload+1); // Little-endian 7A 5C -> 0x5C7A.
bank_expect(word_value==0x5C7A,6);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This excerpt uses far_data_read16 to read payload+1 in bank 3 and checks 5C7A. In the full program, the near read from home2 also confirms that the bank-2 mapping is restored.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 02: the far_call macro and __farcall each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Read a 16-bit value through the bank-aware compiler intrinsic.

u16 far_data_read16(u8 bank, const void* addr)
{
    return __farpeek16(bank, (u16)addr);
}

Read one byte from the supplied ROM bank and address through __farpeek8, then return the byte after restoring the previous bank.

Syntax

u8 far_data_read8(u8 bank, const void* addr);

Parameters

bank

An unsigned 8-bit ROM-bank number. For a call, it must agree with the function's placement; for a read, it selects the source mapping. Use the target cartridge's valid range.

addr

Near pointer to readable source bytes in the selected ROM bank. It does not contain a bank number.

Return value

The byte read, as u8 (0–255).

Conditions and limits

The complete byte or word must be readable in the selected CPU mapping. These reads do not validate pointers, clip addresses or advance automatically to another ROM bank at a window boundary. A word read needs two valid consecutive bytes.

Far reads and copies are synchronous and use shared compiler scratch. Do not let an interrupt run another banked transfer over the same scratch while one is active. On GB, the copy helper also uses one shared HRAM slot for the saved bank. The sample performs these operations from fixed code with no competing banked-transfer handler.

FC switch-bank numbers are logical compiler numbers. Zero denotes common ROM, not a switch target. The helper normalizes zero to bank 1. On SUROM512, only 1–30 are valid: an out-of-range constant passed directly to the switching intrinsic is a build error; an invalid runtime value falls back to 1 and sets the mapper-fault state. Read common ROM directly instead of requesting a bank-zero switch.

Usage example

byte_value=far_data_read8(3,payload); // One byte: 0xD3.
bank_expect(byte_value==0xD3,5);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This excerpt uses far_data_read8 to read payload in bank 3 and checks D3. In the full program, the near read from home2 also confirms that the bank-2 mapping is restored.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 02: the far_call macro and __farcall each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Read one byte from an explicit ROM bank and 16-bit CPU address.

u8 far_data_read8(u8 bank, const void* addr)
{
    return __farpeek8(bank, (u16)addr);
}

Store a bank byte and a CPU-visible pointer in the caller's BankPtr. This constructs a descriptor; it does not switch banks or read the pointed-to bytes.

Syntax

void farptr_make(BankPtr* out, u8 bank, const u8* ptr);

Parameters

out

Pointer to writable storage for one three-byte BankPtr. A null out pointer is ignored and causes no write.

bank

An unsigned 8-bit ROM-bank number. For a call, it must agree with the function's placement; for a read, it selects the source mapping. Use the target cartridge's valid range.

ptr

The 16-bit CPU-visible address to store in the descriptor. It is copied unchanged; this function does not check whether that address exists in the chosen bank.

Return value

None (void).

Usage example

farptr_make(&pointer,3,payload+1); // Store a bank and address; do not read ROM.
bank_expect(pointer.bank==3 && pointer.ptr==payload+1,8);
farptr_make(0,1,home1); // A null destination is ignored.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The descriptor is set to bank 3 and payload+1. Its readers then obtain 7A, 5C7A and the three bytes 7A 5C 96. The null-output call must leave all state unchanged.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 02: the far_call macro and __farcall each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Store a bank/address pair without reading memory; null output is ignored.

void farptr_make(BankPtr* out, u8 bank, const u8* ptr)
{
    if (out == 0) return;
    out->bank = bank;
    out->ptr = ptr;
}

Copy len bytes from a BankPtr into writable RAM. The descriptor is passed by value, so the caller's pointer still identifies the start of the source.

Syntax

void farptr_read(BankPtr ptr, void* dst, u16 len);

Parameters

ptr

A BankPtr value containing both bank and ptr. Pass the descriptor itself, not its address. The caller's descriptor is not modified.

dst

Destination in writable memory. Reserve enough space for every byte copied. Except for a zero-byte transfer, a null or invalid destination is not checked.

len

Byte count, 0–65535. Zero performs no memory copy, but the bank-selection and restoration steps still run.

Return value

None (void).

Conditions and limits

Keep the full source range in the intended ROM mapping and the full destination range in writable memory. Copying does not select the next bank at a window boundary, handle overlapping ranges like memmove, or provide VRAM-safe writes. Use the graphics transfer APIs for VRAM.

Far reads and copies are synchronous and use shared compiler scratch. Do not let an interrupt run another banked transfer over the same scratch while one is active. On GB, the copy helper also uses one shared HRAM slot for the saved bank. The sample performs these operations from fixed code with no competing banked-transfer handler.

FC switch-bank numbers are logical compiler numbers. Zero denotes common ROM, not a switch target. The helper normalizes zero to bank 1. On SUROM512, only 1–30 are valid: an out-of-range constant passed directly to the switching intrinsic is a build error; an invalid runtime value falls back to 1 and sets the mapper-fault state. Read common ROM directly instead of requesting a bank-zero switch.

Usage example

farptr_read(pointer,buffer,3);
bank_expect(buffer[0]==0x7A && buffer[1]==0x5C && buffer[2]==0x96,11);
bank_expect(pointer.bank==3 && pointer.ptr==payload+1,23);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This excerpt copies 3 bytes through farptr_read and checks the buffer against 7A 5C 96. The source descriptor or pointer is retained by the caller; the full program separately checks a zero-length copy and bank restoration.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 02: the far_call macro and __farcall each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Copy len bytes from a far pointer; the caller provides a sufficiently large destination.

void farptr_read(BankPtr ptr, void* dst, u16 len)
{
    __far_memcpy((u8*)dst, ptr.bank, (u16)ptr.ptr, len);
}

Read a little-endian word from the bank and address held in a BankPtr. The descriptor is passed by value and is not advanced.

Syntax

u16 farptr_read16(BankPtr ptr);

Parameters

ptr

A BankPtr value containing both bank and ptr. Pass the descriptor itself, not its address. The caller's descriptor is not modified.

Return value

The little-endian word read, as u16 (0–65535).

Conditions and limits

The complete byte or word must be readable in the selected CPU mapping. These reads do not validate pointers, clip addresses or advance automatically to another ROM bank at a window boundary. A word read needs two valid consecutive bytes.

Far reads and copies are synchronous and use shared compiler scratch. Do not let an interrupt run another banked transfer over the same scratch while one is active. On GB, the copy helper also uses one shared HRAM slot for the saved bank. The sample performs these operations from fixed code with no competing banked-transfer handler.

FC switch-bank numbers are logical compiler numbers. Zero denotes common ROM, not a switch target. The helper normalizes zero to bank 1. On SUROM512, only 1–30 are valid: an out-of-range constant passed directly to the switching intrinsic is a build error; an invalid runtime value falls back to 1 and sets the mapper-fault state. Read common ROM directly instead of requesting a bank-zero switch.

Usage example

bank_expect(farptr_read16(pointer)==0x5C7A,10);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This excerpt uses farptr_read16 to read pointer.ptr in bank 3 and checks 5C7A. In the full program, the near read from home2 also confirms that the bank-2 mapping is restored.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 02: the far_call macro and __farcall each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Read a 16-bit value using both components of the far pointer.

u16 farptr_read16(BankPtr ptr)
{
    return __farpeek16(ptr.bank, (u16)ptr.ptr);
}

Read one byte using both fields of a BankPtr passed by value. The descriptor supplies the bank that an ordinary near pointer cannot carry.

Syntax

u8 farptr_read8(BankPtr ptr);

Parameters

ptr

A BankPtr value containing both bank and ptr. Pass the descriptor itself, not its address. The caller's descriptor is not modified.

Return value

The byte read, as u8 (0–255).

Conditions and limits

The complete byte or word must be readable in the selected CPU mapping. These reads do not validate pointers, clip addresses or advance automatically to another ROM bank at a window boundary. A word read needs two valid consecutive bytes.

Far reads and copies are synchronous and use shared compiler scratch. Do not let an interrupt run another banked transfer over the same scratch while one is active. On GB, the copy helper also uses one shared HRAM slot for the saved bank. The sample performs these operations from fixed code with no competing banked-transfer handler.

FC switch-bank numbers are logical compiler numbers. Zero denotes common ROM, not a switch target. The helper normalizes zero to bank 1. On SUROM512, only 1–30 are valid: an out-of-range constant passed directly to the switching intrinsic is a build error; an invalid runtime value falls back to 1 and sets the mapper-fault state. Read common ROM directly instead of requesting a bank-zero switch.

Usage example

bank_expect(farptr_read8(pointer)==0x7A,9);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This excerpt uses farptr_read8 to read pointer.ptr in bank 3 and checks 7A. In the full program, the near read from home2 also confirms that the bank-2 mapping is restored.

The complete program teaches how a bank number and near address identify data, how callbacks cross banks, and how to distinguish the library's record from the actual mapping. All displayed numbers are hexadecimal. BANK IN and BANK OUT must show 02, BYTE HEX D3, WORD HEX 5C7A, and both FAILED CHECKS and FIRST FAILURE 00. CGB and FC display blue text; DMG displays black text.

CALL COUNT is 02: the far_call macro and __farcall each invoke the callback once.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Read one byte using both the bank and address of the supplied far pointer.

u8 farptr_read8(BankPtr ptr)
{
    return __farpeek8(ptr.bank, (u16)ptr.ptr);
}

Calculate the shortest signed displacement from the current position to a target on an axis whose ends join. Use it for following or distance comparisons across a field edge.

Syntax

s16 chain_wrap_delta(u8 target, u8 current, u16 size);

Parameters

target

Target coordinate, in 0..size−1.

current

Current coordinate, in 0..size−1.

size

Wrapped axis length, 1..256: width for X, height for Y. This is a 16-bit argument so that 256 is representable.

Return value

Return the shortest displacement as s16: positive toward increasing coordinates, negative toward decreasing coordinates, or zero at the same position. Valid inputs produce −128..+128. With screen coordinates, rightward and downward displacements are positive.

Conditions and limits

Include chain.h and compile chain.c exactly once. No Chain or ChainBody initialization is required. The function only calculates a displacement; it does not alter coordinate arrays, joint counts or the screen.

The function does not validate or normalize inputs. Do not pass size=0, size>256, or coordinates at least as large as size. Wrap coordinates from a larger coordinate system into 0..size−1 before calling.

If both routes have the same length, retain the sign of the direct target−current displacement. With size=160, 0→80 returns +80 and 80→0 returns −80. With size=1, zero is the only valid coordinate and the result is zero.

Usage example

distances[0]=chain_wrap_delta(1,159,160);   // +2: cross the right edge.
    distances[1]=chain_wrap_delta(159,1,160);   // -2: cross the left edge.
    distances[2]=chain_wrap_delta(80,0,160);    // +80: keep the direct sign.
    distances[3]=chain_wrap_delta(0,80,160);    // -80: same-length routes.
    distances[4]=chain_wrap_delta(0,0,1);       // 0: the only valid position.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This lesson demonstrates wrapped coordinates. Each arrow goes from the current position to the target. It displays computed results +02/−02 for crossing a width-160 edge, +80/−80 for half a field, and +00 for width 1. The leading zero is decimal padding. The lesson does not draw or move an object.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\chain_wrap.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\chain_wrap.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Return target minus current along the shortest wrapped route.
Supply size 1..256 and coordinates in 0..size-1; inputs are not normalized.
Exactly half a field retains the direct displacement sign.

s16 chain_wrap_delta(u8 target, u8 current, u16 size)
{
    s16 delta;
    s16 half;
    delta = (s16)((s16)target - (s16)current);
    half = (s16)(size >> 1);
    // At exactly half a field, retain the sign of the direct displacement.
    if (((u16)delta & 0x8000) != 0) {
        if ((u16)(0 - delta) > (u16)half) delta = (s16)(delta + (s16)size);
    } else if ((u16)delta > (u16)half) delta = (s16)(delta - (s16)size);
    return delta;
}

Attach three caller-owned joint arrays and set the joint count to zero, without allocating memory.

Syntax

u8 chain_body_init(ChainBody* body, u8* x, u8* y, u8* heading, u8 capacity, u16 width, u16 height);

Parameters

body

Target ChainBody; null is ignored. Except for initialization, pass an initialized state.

x

Array of joint X coordinates.

y

Array of joint Y coordinates.

heading

Array of joint headings.

capacity

Allocated array length, 1..255.

width

Wrapped field width, 1..256.

height

Wrapped field height, 1..256.

Return value

Return 1 on success or 0 for invalid arguments. Failure with a non-null body sets capacity and count to zero, disabling updates.

Conditions and limits

Include chain.h and compile chain.c exactly once. ChainBody holds each joint’s current position and heading. It is a separate state type from the Chain position-history ring.

Supply three separate writable arrays, x, y and heading, each containing capacity bytes. Keep them alive while the body is used. Index zero is the head, included in count. Do not alter storage pointers, capacity or field dimensions after initialization.

Headings use 16 clockwise sectors: 0=right, 4=down, 8=left, 12=up. Only the low four input bits are used. Screen coordinates increase rightward and downward; each dimension is 1..256 pixels.

Usage example

chain_body_init(&body,joint_x,joint_y,joint_heading,8,160,144);
    // Eight caller-owned slots, including the head, on a wrapped 160x144 field.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The image shows a straight body at the top, one update after a downward turn in the middle, and four updates after the turn below. Coordinates are drawn at twice their logical size. The bend travels backward from the head at the right. CGB and FC use red for the head, blue for the body and green for the tail; DMG uses black. Four settling updates separate the duplicated tail after growth. These are three views of the same eight joints, not one 24-joint body.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\chain_body.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\chain_body.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\chain_body.chr --no-cache --no-disasm

Attach three non-overlapping capacity-byte arrays. Return 1 on success.
Invalid storage, zero capacity or dimensions outside 1..256 disable the body.

u8 chain_body_init(ChainBody* body, u8* x, u8* y, u8* heading, u8 capacity, u16 width, u16 height)
{
    if (body == 0) return 0;
    body->x = x;
    body->y = y;
    body->heading = heading;
    body->count = 0;
    body->capacity = 0;
    body->width = width;
    body->height = height;
    if (x == 0 || y == 0 || heading == 0 || capacity == 0) return 0;
    if (width == 0 || width > 256 || height == 0 || height > 256) return 0;
    body->capacity = capacity;
    return 1;
}

Build a straight initial pose by placing joints behind the specified head.

Syntax

u8 chain_body_reset(ChainBody* body, u8 count, u8 head_x, u8 head_y, u8 heading);

Parameters

body

Target ChainBody; null is ignored. Except for initialization, pass an initialized state.

count

Joint count including the head, 1..capacity.

head_x

Head X coordinate, wrapped to the field width.

head_y

Head Y coordinate, wrapped to the field height.

heading

Head heading in the 16-sector system.

Return value

Return 1 on success. A zero or excessive count, or a null body, returns 0 without changing the pose.

Conditions and limits

Include chain.h and compile chain.c exactly once. ChainBody holds each joint’s current position and heading. It is a separate state type from the Chain position-history ring.

Supply three separate writable arrays, x, y and heading, each containing capacity bytes. Keep them alive while the body is used. Index zero is the head, included in count. Do not alter storage pointers, capacity or field dimensions after initialization.

Headings use 16 clockwise sectors: 0=right, 4=down, 8=left, 12=up. Only the low four input bits are used. Screen coordinates increase rightward and downward; each dimension is 1..256 pixels.

Cardinal spacing is four pixels. Intermediate headings use integer vectors such as (4,1), (3,3) and (1,4), so Euclidean distance is not exactly four pixels. The initial pose may cross a field edge.

Usage example

chain_body_reset(&body,7,48,16,0); // Seven joints, facing right.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The image shows a straight body at the top, one update after a downward turn in the middle, and four updates after the turn below. Coordinates are drawn at twice their logical size. The bend travels backward from the head at the right. CGB and FC use red for the head, blue for the body and green for the tail; DMG uses black. Four settling updates separate the duplicated tail after growth. These are three views of the same eight joints, not one 24-joint body.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\chain_body.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\chain_body.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\chain_body.chr --no-cache --no-disasm

Seed count joints in a straight pose behind the head; count includes the head.
Return 0 without changing the pose if count is zero or exceeds capacity.
Coordinates wrap to the playfield and headings are masked to 0..15.

u8 chain_body_reset(ChainBody* body, u8 count, u8 head_x, u8 head_y, u8 heading)
{
    // Cache caller storage once; following math and old-heading propagation
    // use these local values. Avoid decoding packed struct pointers per joint.
    u8* coord_x;u8* coord_y;u8* directions;u16 width;u16 height;
    u8 i;
    u8 x;
    u8 y;
    s16 ox;
    s16 oy;
    if (body == 0) return 0;
    if (count == 0 || count > body->capacity) return 0;
    coord_x=body->x;coord_y=body->y;directions=body->heading;
    width=body->width;height=body->height;
    heading = (u8)(heading & 15);
    x = chain_body_wrap((s16)head_x, width);
    y = chain_body_wrap((s16)head_y, height);
    ox = chain_body_offset_x(heading);
    oy = chain_body_offset_y(heading);
    i = 0;
    while (i < count) {
        coord_x[(__safe_index u8)i] = x;
        coord_y[(__safe_index u8)i] = y;
        directions[(__safe_index u8)i] = heading;
        x = chain_body_wrap((s16)((s16)x - ox), width);
        y = chain_body_wrap((s16)((s16)y - oy), height);
        i = (u8)(i + 1);
    }
    body->count = count;
    return 1;
}

Set the head pose and pull each joint gradually toward a socket behind its predecessor. Heading changes propagate by one joint per update.

Syntax

void chain_body_step(ChainBody* body, u8 head_x, u8 head_y, u8 heading);

Parameters

body

Target ChainBody; null is ignored. Except for initialization, pass an initialized state.

head_x

Head X coordinate, wrapped to the field width.

head_y

Head Y coordinate, wrapped to the field height.

heading

Head heading in the 16-sector system.

Return value

No return value.

Conditions and limits

Include chain.h and compile chain.c exactly once. ChainBody holds each joint’s current position and heading. It is a separate state type from the Chain position-history ring.

Supply three separate writable arrays, x, y and heading, each containing capacity bytes. Keep them alive while the body is used. Index zero is the head, included in count. Do not alter storage pointers, capacity or field dimensions after initialization.

Headings use 16 clockwise sectors: 0=right, 4=down, 8=left, 12=up. Only the low four input bits are used. Screen coordinates increase rightward and downward; each dimension is 1..256 pixels.

Use the predecessor’s updated position to find the target socket, then compute the shortest wrapped displacement on each axis. A zero displacement does not move; magnitude 1..4 moves one pixel, and magnitude 5 or more moves two. At exactly half a field, retain the original displacement sign.

Pass each joint’s saved, pre-update heading to the next joint, allowing a bend to travel through the body. An empty body is unchanged.

The caller handles head velocity, acceleration, collisions, rendering and waiting. Normally update the head first, then call chain_body_step once per simulation tick. This is joint following, not a rigid-body or exact length-constraint solver.

Usage example

chain_body_step(&body,48,20,4); // The head turns down; only joint 1 receives 4.
    show_pose(8,34);
    for(step=1;step<4;step++) {
        chain_body_step(&body,48,(u8)(20+step),4);
    }
    // After four ticks, the new heading has reached joints 1 through 4.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The image shows a straight body at the top, one update after a downward turn in the middle, and four updates after the turn below. Coordinates are drawn at twice their logical size. The bend travels backward from the head at the right. CGB and FC use red for the head, blue for the body and green for the tail; DMG uses black. Four settling updates separate the duplicated tail after growth. These are three views of the same eight joints, not one 24-joint body.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\chain_body.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\chain_body.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\chain_body.chr --no-cache --no-disasm

Install the caller's head pose, then pull joints from front to rear.
Each joint aims four pixels behind its updated predecessor and receives that
predecessor's OLD heading. Each axis moves 1 pixel, or 2 when error exceeds 4.
Call once per simulation tick; this does not advance head physics or render.

void chain_body_step(ChainBody* body, u8 head_x, u8 head_y, u8 heading)
{
    // Cache caller storage once; following math and old-heading propagation
    // use these local values. Avoid decoding packed struct pointers per joint.
    u8* coord_x;u8* coord_y;u8* directions;u16 width;u16 height;
    u8 i;
    u8 previous;
    u8 pull;
    u8 old;
    u8 x;
    u8 y;
    u8 tx;
    u8 ty;
    s16 sx;
    s16 sy;
    if (body == 0) return;
    if (body->count == 0) return;
    coord_x=body->x;coord_y=body->y;directions=body->heading;
    width=body->width;height=body->height;
    heading = (u8)(heading & 15);
    coord_x[0] = chain_body_wrap((s16)head_x, width);
    coord_y[0] = chain_body_wrap((s16)head_y, height);
    directions[0] = heading;
    pull = heading;
    i = 1;
    while (i < body->count) {
        previous = (u8)(i - 1);
        old = directions[(__safe_index u8)i];
        x = coord_x[(__safe_index u8)i];
        y = coord_y[(__safe_index u8)i];
        tx = chain_body_wrap((s16)((s16)coord_x[(__safe_index u8)previous] - chain_body_offset_x(pull)), width);
        ty = chain_body_wrap((s16)((s16)coord_y[(__safe_index u8)previous] - chain_body_offset_y(pull)), height);
        sx = chain_body_correction(chain_wrap_delta(tx, x, width));
        sy = chain_body_correction(chain_wrap_delta(ty, y, height));
        directions[(__safe_index u8)i] = pull;
        coord_x[(__safe_index u8)i] = chain_body_wrap((s16)((s16)x + sx), width);
        coord_y[(__safe_index u8)i] = chain_body_wrap((s16)((s16)y + sy), height);
        // Save before overwriting: a bend advances by one joint per update.
        pull = old;
        i = (u8)(i + 1);
    }
}

Copy the tail’s current position and heading into the next free slot and increase the count by one.

Syntax

u8 chain_body_grow(ChainBody* body);

Parameters

body

Target ChainBody; null is ignored. Except for initialization, pass an initialized state.

Return value

Return 1 if a joint was appended; return 0 for an empty, full, disabled or null body.

Conditions and limits

Include chain.h and compile chain.c exactly once. ChainBody holds each joint’s current position and heading. It is a separate state type from the Chain position-history ring.

Supply three separate writable arrays, x, y and heading, each containing capacity bytes. Keep them alive while the body is used. Index zero is the head, included in count. Do not alter storage pointers, capacity or field dimensions after initialization.

Headings use 16 clockwise sectors: 0=right, 4=down, 8=left, 12=up. Only the low four input bits are used. Screen coordinates increase rightward and downward; each dimension is 1..256 pixels.

The new tail initially overlaps the previous tail, then separates during subsequent chain_body_step calls. Growth itself does not move the head or other joints.

Usage example

chain_body_grow(&body); // Copy the tail pose into the eighth slot.
    chain_body_step(&body,48,16,0);
    chain_body_step(&body,48,16,0);
    chain_body_step(&body,48,16,0);
    chain_body_step(&body,48,16,0); // Allow the duplicated tail to separate.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The image shows a straight body at the top, one update after a downward turn in the middle, and four updates after the turn below. Coordinates are drawn at twice their logical size. The bend travels backward from the head at the right. CGB and FC use red for the head, blue for the body and green for the tail; DMG uses black. Four settling updates separate the duplicated tail after growth. These are three views of the same eight joints, not one 24-joint body.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\chain_body.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\chain_body.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\chain_body.chr --no-cache --no-disasm

Append a copy of the current tail; later steps separate the new joint.
Return 1 on growth, or 0 for an empty, disabled or full body.

u8 chain_body_grow(ChainBody* body)
{
    u8 tail;
    u8 next;
    if (body == 0) return 0;
    next = body->count;
    if (next == 0 || next >= body->capacity) return 0;
    tail = (u8)(next - 1);
    body->x[(__safe_index u8)next] = body->x[(__safe_index u8)tail];
    body->y[(__safe_index u8)next] = body->y[(__safe_index u8)tail];
    body->heading[(__safe_index u8)next] = body->heading[(__safe_index u8)tail];
    body->count = (u8)(next + 1);
    return 1;
}

Set the joint count to zero while retaining the arrays and field settings.

Syntax

void chain_body_clear(ChainBody* body);

Parameters

body

Target ChainBody; null is ignored. Except for initialization, pass an initialized state.

Return value

No return value.

Conditions and limits

Include chain.h and compile chain.c exactly once. ChainBody holds each joint’s current position and heading. It is a separate state type from the Chain position-history ring.

Supply three separate writable arrays, x, y and heading, each containing capacity bytes. Keep them alive while the body is used. Index zero is the head, included in count. Do not alter storage pointers, capacity or field dimensions after initialization.

Headings use 16 clockwise sectors: 0=right, 4=down, 8=left, 12=up. Only the low four input bits are used. Screen coordinates increase rightward and downward; each dimension is 1..256 pixels.

Array bytes are not erased. Use chain_body_reset to start again; calling chain_body_grow immediately after clearing does not append a joint.

Usage example

chain_body_clear(&body); // Forget the pose; the three arrays remain owned by us.

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The image shows a straight body at the top, one update after a downward turn in the middle, and four updates after the turn below. Coordinates are drawn at twice their logical size. The bend travels backward from the head at the right. CGB and FC use red for the head, blue for the body and green for the tail; DMG uses black. Four settling updates separate the duplicated tail after growth. These are three views of the same eight joints, not one 24-joint body.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\chain_body.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\chain_body.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\chain_body.chr --no-cache --no-disasm

Remove all joints while retaining caller-owned storage and playfield settings.

void chain_body_clear(ChainBody* body)
{
    if (body == 0) return;
    body->count = 0;
}

Forget the recorded history so the same backing array can be reused.

Syntax

void chain_clear(Chain* chain);

Parameters

chain

Pointer to the initialized Chain.

Return value

No return value.

Conditions and limits

Resets the count and head to zero without erasing or freeing the backing array. The caller owns both Chain and its point array and must keep them alive. Use a capacity no greater than 128 to avoid overflow in the reader’s eight-bit index addition.

The FC version does nothing when chain == 0.

Usage example

chain_clear(&trail);result[11]=chain_get_count(&trail);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The sample clears a four-point history and verifies that its count becomes zero.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_chain.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_chain.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Forget the recorded points without clearing or freeing the backing storage.

void chain_clear(Chain* chain)
{
    if (chain == 0) return;
    chain->count = 0;
    chain->head = 0;
}

Read the number of positions currently available in the history.

Syntax

u8 chain_get_count(const Chain* chain);

Parameters

chain

Pointer to the initialized Chain.

Return value

Returns a count from zero through capacity, or zero for a null chain.

Conditions and limits

The caller owns both Chain and its point array and must keep them alive. Use a capacity no greater than 128 to avoid overflow in the reader’s eight-bit index addition.

Usage example

result[4]=chain_get_count(&trail);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

After five pushes into four slots the count remains four. It becomes zero after clearing and stays zero for a zero-capacity history.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_chain.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_chain.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Return the number of stored points, or zero for a null chain.

u8 chain_get_count(const Chain* chain)
{
    if (chain == 0) return 0;
    return chain->count;
}

Read a stored position by its age in the history.

Syntax

u8 chain_get_segment(const Chain* chain, u8 index, ChainPoint* out);

Parameters

chain

Pointer to the initialized Chain.

index

Point age: 0 is newest and count - 1 is oldest retained.

out

Separate writable ChainPoint for the result; null causes failure.

Return value

Returns 1 on success or 0 for an invalid request. A non-null out is cleared to (0,0) before validation.

Conditions and limits

Do not alias out with the backing array or Chain: clearing the output would destroy source data. The caller owns both Chain and its point array and must keep them alive. Use a capacity no greater than 128 to avoid overflow in the reader’s eight-bit index addition.

Usage example

result[1]=chain_get_segment(&trail,0,&point);result[2]=point.x;result[3]=point.y;

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Index 0 reads newest (40,24), index 3 reads oldest (16,8), and invalid index 4 returns failure with output (0,0).

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_chain.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_chain.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Read a point by age, with index zero denoting the newest point. Return zero
for an invalid request and clear a non-null output first. Keep head + index
within the 8-bit range: addition is narrowed before the capacity wrap.

u8 chain_get_segment(const Chain* chain, u8 index, ChainPoint* out)
{
    u8 pos;
    // Do not alias out with the backing ring: it is cleared before the requested point is read.
    if (out != 0) {
        out->x = 0;
        out->y = 0;
    }

    if (out == 0) return 0;
    if (chain == 0) return 0;
    if (chain->capacity == 0) return 0;
    if (index >= chain->count) return 0;

    pos = (u8)(chain->head + index);
    while (pos >= chain->capacity) {
        pos = (u8)(pos - chain->capacity);
    }
    out->x = chain->points[(__safe_index u8)pos].x;
    out->y = chain->points[(__safe_index u8)pos].y;
    return 1;
}

Attach storage to a circular position history and start with no recorded points.

Syntax

void chain_init(Chain* chain, ChainPoint* storage, u8 capacity);

Parameters

chain

Writable Chain to initialize.

storage

Array with room for capacity ChainPoint entries.

capacity

Number of point slots. Use 1–128 for a usable history; zero disables recording.

Return value

No return value.

Conditions and limits

The caller owns both Chain and its point array and must keep them alive. Use a capacity no greater than 128 to avoid overflow in the reader’s eight-bit index addition.

The FC version does nothing when chain == 0.

Usage example

chain_init(&trail,storage,4);result[0]=chain_get_count(&trail);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The example attaches four point slots and checks that the initial count is zero.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_chain.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_chain.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Attach caller-owned ring storage and start with no recorded points.
The storage must remain valid for the lifetime of the chain.

void chain_init(Chain* chain, ChainPoint* storage, u8 capacity)
{
    if (chain == 0) return;
    // A nonzero capacity requires writable storage for that many complete ChainPoint records.
    chain->points = storage;
    chain->capacity = capacity;
    chain->count = 0;
    chain->head = 0;
}

Add the newest position at the head of the history, replacing the oldest point when full.

Syntax

void chain_push_head(Chain* chain, s16 x, s16 y);

Parameters

chain

Pointer to the initialized Chain.

x

Signed X coordinate of the new point.

y

Signed Y coordinate of the new point.

Return value

No return value.

Conditions and limits

A null chain or zero capacity is a no-op. The caller owns both Chain and its point array and must keep them alive. Use a capacity no greater than 128 to avoid overflow in the reader’s eight-bit index addition.

Usage example

chain_push_head(&trail,8,8);chain_push_head(&trail,16,8);chain_push_head(&trail,24,16);chain_push_head(&trail,32,16);chain_push_head(&trail,40,24);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Five pushes into four slots leave (40,24) as the newest point and (16,8) as the oldest retained point; the original (8,8) is replaced.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_chain.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_chain.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Move the ring head backward and store the newest point. Once full, each push
replaces the oldest point; zero capacity is a no-op.

void chain_push_head(Chain* chain, s16 x, s16 y)
{
    if (chain == 0) return;
    if (chain->capacity == 0) return;

    if (chain->head == 0) chain->head = (u8)(chain->capacity - 1);
    else chain->head = (u8)(chain->head - 1);

    chain->points[(__safe_index u8)chain->head].x = x;
    chain->points[(__safe_index u8)chain->head].y = y;

    if (chain->count < chain->capacity) chain->count = (u8)(chain->count + 1);
}

Test whether a point is inside an FC rectangle, including left/top edges and excluding right/bottom edges.

Syntax

unsigned char nes_box16_contains_point(struct NesBox16* box, unsigned short px, unsigned short py);

Parameters

box

Readable NesBox16; do not pass null.

px

Unsigned 16-bit point X coordinate.

py

Unsigned 16-bit point Y coordinate.

Return value

Returns 1 inside, 0 outside.

Conditions and limits

x, y are unsigned 16-bit coordinates; width and height are bytes. Use positive dimensions and keep edge sums no greater than 65535. This does not handle rectangles crossing coordinate wraparound.

Usage example

result[6]=nes_box16_contains_point(&na,9,1);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Each coordinate unit occupies one tile. Rectangles A at (1,1) and B at (5,4) are both 8×6. A-only cells show A, B-only cells show B, and the 4×3 overlap shows 12 O cells. A’s right edge x=9 is excluded. On CGB, A is red, B blue and O green.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_geometry.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_geometry.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Test a half-open box: left/top edges are included and right/bottom edges
excluded. Callers provide valid pointers and non-overflowing edge coordinates.

unsigned char nes_box16_contains_point(struct NesBox16* box, unsigned short px, unsigned short py)
{
    unsigned short right;
    unsigned short bottom;

    right = (unsigned short)(box->x + box->w);
    bottom = (unsigned short)(box->y + box->h);

    if (px < box->x)
    {
        return 0;
    }
    if (py < box->y)
    {
        return 0;
    }
    if (px >= right)
    {
        return 0;
    }
    if (py >= bottom)
    {
        return 0;
    }

    return 1;
}

Test positive-area overlap between two FC rectangles passed by pointer.

Syntax

unsigned char nes_box16_intersects(struct NesBox16* a, struct NesBox16* b);

Parameters

a

Readable first NesBox16; do not pass null.

b

Readable second NesBox16.

Return value

Returns 1 for overlap and 0 for separation or edge contact.

Conditions and limits

x, y are unsigned 16-bit coordinates; width and height are bytes. Use positive dimensions and keep edge sums no greater than 65535. This does not handle rectangles crossing coordinate wraparound.

Usage example

result[5]=nes_box16_intersects(&na,&nb);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Each coordinate unit occupies one tile. Rectangles A at (1,1) and B at (5,4) are both 8×6. A-only cells show A, B-only cells show B, and the 4×3 overlap shows 12 O cells. A’s right edge x=9 is excluded. On CGB, A is red, B blue and O green.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_geometry.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_geometry.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Test two axis-aligned world boxes using exclusive right/bottom edges.
Coordinate-plus-size sums must fit u16; touching edges return false.
Both boxes must have positive dimensions; the overlap test has no separate empty-box guard.

unsigned char nes_box16_intersects(struct NesBox16* a, struct NesBox16* b)
{
    unsigned short a_right;
    unsigned short b_right;
    unsigned short a_bottom;
    unsigned short b_bottom;

    a_right = (unsigned short)(a->x + a->w);
    b_right = (unsigned short)(b->x + b->w);
    a_bottom = (unsigned short)(a->y + a->h);
    b_bottom = (unsigned short)(b->y + b->h);

    if (a_right <= b->x)
    {
        return 0;
    }
    if (b_right <= a->x)
    {
        return 0;
    }
    if (a_bottom <= b->y)
    {
        return 0;
    }
    if (b_bottom <= a->y)
    {
        return 0;
    }

    return 1;
}

Retain an assertion failure code and attempt to append an ASSERT entry.

Syntax

void debug_assert_fail(u16 code);

Parameters

code

16-bit error identifier to retain.

Return value

No return value.

Conditions and limits

Execution continues. The last assertion code updates even when the log is full. The log holds 32 entries by default and drops new entries when full. If overriding DEBUG_TRACE_MAX, use 1–255 consistently in every translation unit. Names are retained as pointers rather than copied; keep their storage readable until inspection finishes. Serialize interrupt and main-thread writers yourself.

Usage example

debug_assert_fail(42);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The sample records code 42, fills the log, then records code 999. The count stays 32 while the last code becomes 999.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Store the assertion code even if the log is full, then attempt an ASSERT
entry. The helper records failure but does not stop execution.

void debug_assert_fail(u16 code)
{
    kq_debug_last_assert = code;
    debug_push(debug_assert_label, code);
}

Read the latest assertion code independently of available log space.

Syntax

u16 debug_get_last_assert(void);

Return value

Returns the latest 16-bit code, initially zero after initialization.

Conditions and limits

Zero is also the initial value and cannot distinguish a failure recorded with code zero. Reading does not clear the code.

Usage example

result[22]=debug_get_last_assert();

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The sample checks 77 from the assertion macro, 999 after the log fills, and zero after reinitialization.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Read the latest assertion code, initially zero after debug_init.

u16 debug_get_last_assert(void)
{
    return kq_debug_last_assert;
}

Read the number of valid entries in the trace array.

Syntax

u8 debug_get_trace_count(void);

Return value

Returns a count from zero through DEBUG_TRACE_MAX.

Conditions and limits

The log holds 32 entries by default and drops new entries when full. If overriding DEBUG_TRACE_MAX, use 1–255 consistently in every translation unit. Names are retained as pointers rather than copied; keep their storage readable until inspection finishes. Serialize interrupt and main-thread writers yourself.

Usage example

result[1]=debug_get_trace_count();

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The sample verifies ten initial entries and the limit of 32 after further writes; the count does not wrap when full.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Read the number of valid entries in the fixed trace buffer.

u8 debug_get_trace_count(void)
{
    return kq_debug_trace_count;
}

Obtain a reference to the internal array to inspect recorded names, values and frame tags.

Syntax

const DebugTraceEntry* debug_get_trace_log(void);

Return value

Returns a read-only pointer to the internal DebugTraceEntry array.

Conditions and limits

This is not a copy. Read only the number of entries reported by debug_get_trace_count(). Stale bytes left after initialization are not valid records. The log holds 32 entries by default and drops new entries when full. If overriding DEBUG_TRACE_MAX, use 1–255 consistently in every translation unit. Names are retained as pointers rather than copied; keep their storage readable until inspection finishes. Serialize interrupt and main-thread writers yourself.

Usage example

entries=debug_get_trace_log();for(i=0;i<10;i++){result[2+i]=entries[i].value;result[12+i]=entries[i].frame;}

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The sample reads all ten value and frame fields and checks the leading B in the BEGIN label.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Borrow the internal trace array; bound inspection by debug_get_trace_count.

const DebugTraceEntry* debug_get_trace_log(void)
{
    return kq_debug_trace_log;
}

Initialize the valid log length, frame tag and last assertion code.

Syntax

void debug_init(void);

Return value

No return value.

Conditions and limits

Existing entry bytes are not erased. Call this before recording the first entry. The log holds 32 entries by default and drops new entries when full. If overriding DEBUG_TRACE_MAX, use 1–255 consistently in every translation unit. Names are retained as pointers rather than copied; keep their storage readable until inspection finishes. Serialize interrupt and main-thread writers yourself.

Usage example

debug_init();result[0]=debug_get_trace_count();

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The sample checks an initial count of zero, then resets a populated log and verifies that count and assertion code clear while old array values remain.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Build the RAM-resident ASSERT label and reset log length, frame tag and last
assertion code. Old log storage bytes are not erased.

void debug_init(void)
{
    debug_assert_label[0] = 'A';
    debug_assert_label[1] = 'S';
    debug_assert_label[2] = 'S';
    debug_assert_label[3] = 'E';
    debug_assert_label[4] = 'R';
    debug_assert_label[5] = 'T';
    debug_assert_label[6] = 0;
    kq_debug_trace_count = 0;
    kq_debug_frame = 0;
    kq_debug_last_assert = 0;
}

Record a named frame marker to identify a point in the workflow.

Syntax

void debug_mark_frame(const u8* label);

Parameters

label

Zero-terminated label stored in memory that remains readable until inspection.

Return value

No return value.

Conditions and limits

The log holds 32 entries by default and drops new entries when full. If overriding DEBUG_TRACE_MAX, use 1–255 consistently in every translation unit. Names are retained as pointers rather than copied; keep their storage readable until inspection finishes. Serialize interrupt and main-thread writers yourself.

Usage example

debug_mark_frame("BEGIN");

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Adding the BEGIN marker records value 65535 (0xFFFF) with frame tag 513.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Append a named marker with the reserved marker value 0xFFFF.

void debug_mark_frame(const u8* label)
{
    debug_push(label, 0xFFFF);
}

Set the frame tag copied into subsequent log entries.

Syntax

void debug_set_frame(u16 frame);

Parameters

frame

16-bit frame number for subsequent entries.

Return value

No return value.

Conditions and limits

This neither waits for a frame nor increments the tag automatically. Pass the game’s frame counter explicitly. The log holds 32 entries by default and drops new entries when full. If overriding DEBUG_TRACE_MAX, use 1–255 consistently in every translation unit. Names are retained as pointers rather than copied; keep their storage readable until inspection finishes. Serialize interrupt and main-thread writers yourself.

Usage example

debug_set_frame(513);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The sample sets 513, records ten entries and reads back all ten frame fields to verify the tag.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Choose the frame tag stored in subsequent debug entries.

void debug_set_frame(u16 frame)
{
    kq_debug_frame = frame;
}

Log a named 16-bit score or counter.

Syntax

void debug_trace_u16(const u8* name, u16 value);

Parameters

name

Zero-terminated label stored in memory that remains readable until inspection.

value

Value from 0 through 65535 to record.

Return value

No return value.

Conditions and limits

The log holds 32 entries by default and drops new entries when full. If overriding DEBUG_TRACE_MAX, use 1–255 consistently in every translation unit. Names are retained as pointers rather than copied; keep their storage readable until inspection finishes. Serialize interrupt and main-thread writers yourself.

Usage example

debug_trace_u16("WORD",4660);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The WORD entry stores 4660 (0x1234), and the sample reads it back to check both bytes.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Append a 16-bit value with the current frame tag.

void debug_trace_u16(const u8* name, u16 value)
{
    debug_push(name, value);
}

Log an eight-bit state value with its name and current frame tag.

Syntax

void debug_trace_u8(const u8* name, u8 value);

Parameters

name

Zero-terminated label stored in memory that remains readable until inspection.

value

Value from 0 through 255, zero-extended into the log’s 16-bit field.

Return value

No return value.

Conditions and limits

The log holds 32 entries by default and drops new entries when full. If overriding DEBUG_TRACE_MAX, use 1–255 consistently in every translation unit. Names are retained as pointers rather than copied; keep their storage readable until inspection finishes. Serialize interrupt and main-thread writers yourself.

Usage example

debug_trace_u8("BYTE",255);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The BYTE entry records 255 and verifies that the log’s 16-bit value field contains 255.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Widen a byte value into the trace entry's 16-bit value field.

void debug_trace_u8(const u8* name, u8 value)
{
    debug_push(name, (u16)value);
}

A statement-like macro that records assertion code 1 when its condition is false.

Syntax

#define KITAQGB_ASSERT(cond) do { if (!(cond)) debug_assert_fail((u16)1); } while (0)

Parameters

cond

Condition expected to hold; zero means failure.

Return value

No return value.

Conditions and limits

The condition is evaluated once. True records nothing; false records a failure without stopping execution. Its do…while (0) form makes it usable as one statement in an if…else.

Usage example

KITAQGB_ASSERT(1);KITAQGB_ASSERT(0);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

One true and one false assertion produce exactly one entry with code 1.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

#define KITAQGB_ASSERT(cond) do { if (!(cond)) debug_assert_fail((u16)1); } while (0)

Record a chosen assertion code only when the condition is false.

Syntax

#define KITAQGB_ASSERT_CODE(cond, code) do { if (!(cond)) debug_assert_fail((u16)(code)); } while (0)

Parameters

cond

Condition expected to hold.

code

Code expression evaluated on failure and converted to 16 bits.

Return value

No return value.

Conditions and limits

The condition is evaluated once; the code expression is evaluated only on failure. Execution continues after recording.

Usage example

KITAQGB_ASSERT_CODE(1,++side_effect);KITAQGB_ASSERT_CODE(0,77);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

With a true condition, the code expression ++side_effect is not evaluated and the variable stays zero. A false condition records code 77.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

#define KITAQGB_ASSERT_CODE(cond, code) do { if (!(cond)) debug_assert_fail((u16)(code)); } while (0)

Cast a label to a string pointer and append a frame marker with value 0xFFFF.

Syntax

#define KITAQGB_MARK_FRAME(label) debug_mark_frame((const u8*)(label))

Parameters

label

Zero-terminated label stored in memory that remains readable until inspection.

Return value

No return value.

Conditions and limits

The log holds 32 entries by default and drops new entries when full. If overriding DEBUG_TRACE_MAX, use 1–255 consistently in every translation unit. Names are retained as pointers rather than copied; keep their storage readable until inspection finishes. Serialize interrupt and main-thread writers yourself.

Usage example

KITAQGB_MARK_FRAME("END");

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The END marker is verified with value 65535 and frame tag 513.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

#define KITAQGB_MARK_FRAME(label) debug_mark_frame((const u8*)(label))

Log a named value after explicitly converting it to 16 bits.

Syntax

#define KITAQGB_TRACE(name, value) debug_trace_u16((const u8*)(name), (u16)(value))

Parameters

name

Zero-terminated label stored in memory that remains readable until inspection.

value

Expression converted to 16 bits before recording.

Return value

No return value.

Conditions and limits

The macro is always active; build settings do not automatically disable it. It has the same 16-bit logging behavior as KITAQGB_TRACE_U16. The log holds 32 entries by default and drops new entries when full. If overriding DEBUG_TRACE_MAX, use 1–255 consistently in every translation unit. Names are retained as pointers rather than copied; keep their storage readable until inspection finishes. Serialize interrupt and main-thread writers yourself.

Usage example

KITAQGB_TRACE("SCORE",600);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The example records 600. The value is read back from the log for verification.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

#define KITAQGB_TRACE(name, value) debug_trace_u16((const u8*)(name), (u16)(value))

Log a named value after explicitly converting it to 16 bits.

Syntax

#define KITAQGB_TRACE_U16(name, value) debug_trace_u16((const u8*)(name), (u16)(value))

Parameters

name

Zero-terminated label stored in memory that remains readable until inspection.

value

Expression converted to 16 bits before recording.

Return value

No return value.

Conditions and limits

The macro is always active; build settings do not automatically disable it. The log holds 32 entries by default and drops new entries when full. If overriding DEBUG_TRACE_MAX, use 1–255 consistently in every translation unit. Names are retained as pointers rather than copied; keep their storage readable until inspection finishes. Serialize interrupt and main-thread writers yourself.

Usage example

KITAQGB_TRACE_U16("WORD2",500);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The example records 500. The value is read back from the log for verification.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

#define KITAQGB_TRACE_U16(name, value) debug_trace_u16((const u8*)(name), (u16)(value))

Log a named value after explicitly converting it to 8 bits.

Syntax

#define KITAQGB_TRACE_U8(name, value) debug_trace_u8((const u8*)(name), (u8)(value))

Parameters

name

Zero-terminated label stored in memory that remains readable until inspection.

value

Expression converted to 8 bits before recording.

Return value

No return value.

Conditions and limits

The macro is always active; build settings do not automatically disable it. The log holds 32 entries by default and drops new entries when full. If overriding DEBUG_TRACE_MAX, use 1–255 consistently in every translation unit. Names are retained as pointers rather than copied; keep their storage readable until inspection finishes. Serialize interrupt and main-thread writers yourself.

Usage example

KITAQGB_TRACE_U8("CAST",0x1234);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The example records 52. Only the low byte 0x34 of 0x1234 is retained.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

#define KITAQGB_TRACE_U8(name, value) debug_trace_u8((const u8*)(name), (u8)(value))

Release all entities and reset their fields, including the no-sprite marker.

Syntax

void entity_clear_all(void);

Return value

None (void).

Conditions and limits

The pool is a fixed array: no heap allocation occurs. ENTITY_MAX defaults to 16 and must be 1–255, defined identically in every compilation unit. Slot IDs start at zero; 0xFF is reserved for failure.

Reset active,type,x,y,vx,vy,state,timer to zero and sprite to 0xFF for every slot. This does not hide or free hardware sprites; clean up rendering resources separately.

Usage example

entity_clear_all();
after_clear = entity_count_active();
if (after_clear != 0 || entity_get(reused) != 0) { failures++; }

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program teaches the lifetime of a reusable pool slot. Read the labels with the numbers: CREATED 002 after two allocations; AFTER FREE 001 after freeing the first; REUSED ID 000 when the lowest free ID is reused; AFTER CLEAR 000 after clearing the pool. It checks null lookup after release and reset fields after reuse. FAILED CHECKS 000 means these checks matched the expected values.

The FC traversal calls each callback for the two active entities: UPDATE CALLS 002 and DRAW CALLS 002. The sample's update callback moves both one tile to the right. Its drawing callback places A at tile (3,12) and B at (7,12), representing the two objects. These are background font tiles drawn by the callback, not automatically allocated sprites.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Release every entity and restore deterministic defaults, including the no-sprite sentinel.

void entity_clear_all(void)
{
    u8 i;
    i = 0;
    while (i < ENTITY_MAX) {
        entity_pool[(__safe_index u8)i].active = 0;
        entity_pool[(__safe_index u8)i].type = 0;
        entity_pool[(__safe_index u8)i].x = 0;
        entity_pool[(__safe_index u8)i].y = 0;
        entity_pool[(__safe_index u8)i].vx = 0;
        entity_pool[(__safe_index u8)i].vy = 0;
        entity_pool[(__safe_index u8)i].state = 0;
        entity_pool[(__safe_index u8)i].timer = 0;
        entity_pool[(__safe_index u8)i].sprite = 0xFF;
        i = (u8)(i + 1);
    }
}

Count the occupied entity slots without modifying them.

Syntax

u8 entity_count_active(void);

Return value

Number of slots whose active byte is nonzero, from 0 to ENTITY_MAX. This is occupancy, not the highest allocated ID or the number of sprites on screen.

Conditions and limits

The pool is a fixed array: no heap allocation occurs. ENTITY_MAX defaults to 16 and must be 1–255, defined identically in every compilation unit. Slot IDs start at zero; 0xFF is reserved for failure.

Usage example

created = entity_count_active();
if (created != 2) { failures++; }

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program teaches the lifetime of a reusable pool slot. Read the labels with the numbers: CREATED 002 after two allocations; AFTER FREE 001 after freeing the first; REUSED ID 000 when the lowest free ID is reused; AFTER CLEAR 000 after clearing the pool. It checks null lookup after release and reset fields after reuse. FAILED CHECKS 000 means these checks matched the expected values.

The FC traversal calls each callback for the two active entities: UPDATE CALLS 002 and DRAW CALLS 002. The sample's update callback moves both one tile to the right. Its drawing callback places A at tile (3,12) and B at (7,12), representing the two objects. These are background font tiles drawn by the callback, not automatically allocated sprites.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Count occupied slots without changing entity state.

u8 entity_count_active(void)
{
    u8 i;
    u8 count;
    i = 0;
    count = 0;
    while (i < ENTITY_MAX) {
        if (entity_pool[(__safe_index u8)i].active != 0) count = (u8)(count + 1);
        i = (u8)(i + 1);
    }
    return count;
}

Allocate an entity with the supplied type and position; return its reusable ID, or 0xFF when full.

Syntax

u8 entity_create(u8 type, s16 x, s16 y);

Parameters

type

Application-defined type tag, 0–255. The pool stores it but does not choose behavior or drawing routines from it.

x, y

Signed 16-bit coordinates (-32768–32767). Their unit is chosen by the game, such as pixels or Q8.8; the pool does not convert units, clip positions or apply velocity automatically.

Return value

The lowest free slot ID (0–ENTITY_MAX-1), or 0xFF when none is free. A successful allocation sets active=1, stores the supplied type and position, clears velocity/state/timer, and sets sprite=0xFF.

Conditions and limits

The pool is a fixed array: no heap allocation occurs. ENTITY_MAX defaults to 16 and must be 1–255, defined identically in every compilation unit. Slot IDs start at zero; 0xFF is reserved for failure.

Usage example

first = entity_create(1, 2, 12);
second = entity_create(2, 6, 12);
if (first == 0xFF || second == 0xFF) { failures++; }

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program teaches the lifetime of a reusable pool slot. Read the labels with the numbers: CREATED 002 after two allocations; AFTER FREE 001 after freeing the first; REUSED ID 000 when the lowest free ID is reused; AFTER CLEAR 000 after clearing the pool. It checks null lookup after release and reset fields after reuse. FAILED CHECKS 000 means these checks matched the expected values.

The FC traversal calls each callback for the two active entities: UPDATE CALLS 002 and DRAW CALLS 002. The sample's update callback moves both one tile to the right. Its drawing callback places A at tile (3,12) and B at (7,12), representing the two objects. These are background font tiles drawn by the callback, not automatically allocated sprites.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Returns a reusable slot ID, or 0xFF if no slot is free.

u8 entity_create(u8 type, s16 x, s16 y)
{
    u8 i;
    i = 0;
    while (i < ENTITY_MAX) {
        if (entity_pool[(__safe_index u8)i].active == 0) {
            entity_pool[(__safe_index u8)i].active = 1;
            entity_pool[(__safe_index u8)i].type = type;
            entity_pool[(__safe_index u8)i].x = x;
            entity_pool[(__safe_index u8)i].y = y;
            entity_pool[(__safe_index u8)i].vx = 0;
            entity_pool[(__safe_index u8)i].vy = 0;
            entity_pool[(__safe_index u8)i].state = 0;
            entity_pool[(__safe_index u8)i].timer = 0;
            entity_pool[(__safe_index u8)i].sprite = 0xFF;
            return i;
        }
        i = (u8)(i + 1);
    }
    return 0xFF;
}

Release the entity slot identified by id; its stored payload is not cleared until reallocation.

Syntax

void entity_destroy(u8 id);

Parameters

id

Reusable slot index from 0 to ENTITY_MAX-1. Values outside that range are invalid. Destroying an invalid ID has no effect; looking it up returns null.

Return value

None (void).

Conditions and limits

The pool is a fixed array: no heap allocation occurs. ENTITY_MAX defaults to 16 and must be 1–255, defined identically in every compilation unit. Slot IDs start at zero; 0xFF is reserved for failure.

Destroy only clears active; it does not erase the other fields, free a sprite, or release assets. A later create can reuse the same ID and address for a different entity. Arrange associated resource cleanup in the game.

Usage example

entity_destroy(first);
after_free = entity_count_active();
if (entity_get(first) != 0 || after_free != 1) { failures++; }

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program teaches the lifetime of a reusable pool slot. Read the labels with the numbers: CREATED 002 after two allocations; AFTER FREE 001 after freeing the first; REUSED ID 000 when the lowest free ID is reused; AFTER CLEAR 000 after clearing the pool. It checks null lookup after release and reset fields after reuse. FAILED CHECKS 000 means these checks matched the expected values.

The FC traversal calls each callback for the two active entities: UPDATE CALLS 002 and DRAW CALLS 002. The sample's update callback moves both one tile to the right. Its drawing callback places A at tile (3,12) and B at (7,12), representing the two objects. These are background font tiles drawn by the callback, not automatically allocated sprites.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Release a valid slot without clearing its payload. Reallocation resets the payload;
a saved pointer or ID must not be treated as a persistent entity identity.

void entity_destroy(u8 id)
{
    if (id >= ENTITY_MAX) return;
    entity_pool[(__safe_index u8)id].active = 0;
}

Traverse active entities and call the supplied drawing callback with each ID. This uses the same traversal as entity_update_all; no sprite or pixel is drawn unless the callback submits drawing data.

Syntax

void entity_draw_all(EntityFn fn);

Parameters

fn

Function pointer with signature void fn(u8 id). It receives a slot ID; use entity_get(id) to access fields. Null is accepted and causes no calls.

Return value

None (void).

Conditions and limits

The pool is a fixed array: no heap allocation occurs. ENTITY_MAX defaults to 16 and must be 1–255, defined identically in every compilation unit. Slot IDs start at zero; 0xFF is reserved for failure.

The scan tests activity when it reaches a slot. A callback can deactivate a later slot so it is skipped, or activate a later slot so it is visited in this pass. This is not a snapshot of the initial active set.

Place the callback in common PRG bank 0, or keep its bank mapped throughout the call. A function pointer contains a 16-bit CPU address and does not select a bank. FC function parameters and local variables use static storage: do not call an entity traversal recursively or reenter it from an interrupt.

Usage example

void demo_draw(u8 id) {
    Entity* entity;
    entity = entity_get(id);
    if (entity != 0) {
        m_put((u8)entity->x, (u8)entity->y, (u8)('A' + entity->type - 1));
        draw_calls++;
    }
}

// From main(), after creating two entities:
draw_calls = 0;
entity_draw_all(demo_draw);
automatic_draws = draw_calls;
if (automatic_draws != 2) { failures++; }

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program teaches the lifetime of a reusable pool slot. Read the labels with the numbers: CREATED 002 after two allocations; AFTER FREE 001 after freeing the first; REUSED ID 000 when the lowest free ID is reused; AFTER CLEAR 000 after clearing the pool. It checks null lookup after release and reset fields after reuse. FAILED CHECKS 000 means these checks matched the expected values.

The FC traversal calls each callback for the two active entities: UPDATE CALLS 002 and DRAW CALLS 002. The sample's update callback moves both one tile to the right. Its drawing callback places A at tile (3,12) and B at (7,12), representing the two objects. These are background font tiles drawn by the callback, not automatically allocated sprites.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Call the drawing callback for each active slot, using the same traversal rules as update.
The callback submits drawing data; the pool does not allocate sprites.

void entity_draw_all(EntityFn fn)
{
    entity_update_all(fn);
}

Return a pointer to the active entity, or null for an invalid or inactive ID. The pointer refers to reusable pool storage.

Syntax

Entity* entity_get(u8 id);

Parameters

id

Reusable slot index from 0 to ENTITY_MAX-1. Values outside that range are invalid. Destroying an invalid ID has no effect; looking it up returns null.

Return value

A writable pointer to the active pool slot, or null if the ID is invalid or inactive. The storage belongs to the pool; do not free it or use it as a permanent identity across destroy/recreate operations.

Conditions and limits

The pool is a fixed array: no heap allocation occurs. ENTITY_MAX defaults to 16 and must be 1–255, defined identically in every compilation unit. Slot IDs start at zero; 0xFF is reserved for failure.

Destroy only clears active; it does not erase the other fields, free a sprite, or release assets. A later create can reuse the same ID and address for a different entity. Arrange associated resource cleanup in the game.

Usage example

current_entity = entity_get(first);
if (current_entity != 0) { current_entity->vx = 5; }
else { failures++; }

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program teaches the lifetime of a reusable pool slot. Read the labels with the numbers: CREATED 002 after two allocations; AFTER FREE 001 after freeing the first; REUSED ID 000 when the lowest free ID is reused; AFTER CLEAR 000 after clearing the pool. It checks null lookup after release and reset fields after reuse. FAILED CHECKS 000 means these checks matched the expected values.

The FC traversal calls each callback for the two active entities: UPDATE CALLS 002 and DRAW CALLS 002. The sample's update callback moves both one tile to the right. Its drawing callback places A at tile (3,12) and B at (7,12), representing the two objects. These are background font tiles drawn by the callback, not automatically allocated sprites.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Returns null for an invalid or inactive ID; the returned pointer aliases reusable pool storage.

Entity* entity_get(u8 id)
{
    if (id >= ENTITY_MAX) return 0;
    if (entity_pool[(__safe_index u8)id].active == 0) return 0;
    return &entity_pool[(__safe_index u8)id];
}

Initialize the entity pool by resetting every slot.

Syntax

void entity_init(void);

Return value

None (void).

Conditions and limits

The pool is a fixed array: no heap allocation occurs. ENTITY_MAX defaults to 16 and must be 1–255, defined identically in every compilation unit. Slot IDs start at zero; 0xFF is reserved for failure.

Reset active,type,x,y,vx,vy,state,timer to zero and sprite to 0xFF for every slot. This does not hide or free hardware sprites; clean up rendering resources separately.

Usage example

entity_init();
if (entity_count_active() != 0) { failures++; }

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program teaches the lifetime of a reusable pool slot. Read the labels with the numbers: CREATED 002 after two allocations; AFTER FREE 001 after freeing the first; REUSED ID 000 when the lowest free ID is reused; AFTER CLEAR 000 after clearing the pool. It checks null lookup after release and reset fields after reuse. FAILED CHECKS 000 means these checks matched the expected values.

The FC traversal calls each callback for the two active entities: UPDATE CALLS 002 and DRAW CALLS 002. The sample's update callback moves both one tile to the right. Its drawing callback places A at tile (3,12) and B at (7,12), representing the two objects. These are background font tiles drawn by the callback, not automatically allocated sprites.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Reset every slot before the game starts using the pool.

void entity_init(void)
{
    entity_clear_all();
}

Visit active slots in ascending ID order and call fn(id) once for each. The callback implements movement, collisions or timers; the pool does not supply that logic. A null callback does nothing.

Syntax

void entity_update_all(EntityFn fn);

Parameters

fn

Function pointer with signature void fn(u8 id). It receives a slot ID; use entity_get(id) to access fields. Null is accepted and causes no calls.

Return value

None (void).

Conditions and limits

The pool is a fixed array: no heap allocation occurs. ENTITY_MAX defaults to 16 and must be 1–255, defined identically in every compilation unit. Slot IDs start at zero; 0xFF is reserved for failure.

The scan tests activity when it reaches a slot. A callback can deactivate a later slot so it is skipped, or activate a later slot so it is visited in this pass. This is not a snapshot of the initial active set.

Place the callback in common PRG bank 0, or keep its bank mapped throughout the call. A function pointer contains a 16-bit CPU address and does not select a bank. FC function parameters and local variables use static storage: do not call an entity traversal recursively or reenter it from an interrupt.

Usage example

void demo_update(u8 id) {
    Entity* entity;
    entity = entity_get(id);
    if (entity != 0) { entity->x = entity->x + 1; update_calls++; }
}

// From main(), after creating two entities:
update_calls = 0;
entity_update_all(demo_update);
automatic_updates = update_calls;
if (automatic_updates != 2) { failures++; }

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The complete program teaches the lifetime of a reusable pool slot. Read the labels with the numbers: CREATED 002 after two allocations; AFTER FREE 001 after freeing the first; REUSED ID 000 when the lowest free ID is reused; AFTER CLEAR 000 after clearing the pool. It checks null lookup after release and reset fields after reuse. FAILED CHECKS 000 means these checks matched the expected values.

The FC traversal calls each callback for the two active entities: UPDATE CALLS 002 and DRAW CALLS 002. The sample's update callback moves both one tile to the right. Its drawing callback places A at tile (3,12) and B at (7,12), representing the two objects. These are background font tiles drawn by the callback, not automatically allocated sprites.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Call fn(id) for each active slot in ascending order. A null callback does nothing.
Changes to later slots take effect during the same traversal. Do not reenter this traversal.

void entity_update_all(EntityFn fn)
{
    u8 i;
    if (fn == 0) return;
    i = 0;
    while (i < ENTITY_MAX) {
        if (entity_pool[(__safe_index u8)i].active != 0) fn(i);
        i = (u8)(i + 1);
    }
}

Divide Q8.8 values after reducing the operands.

Syntax

fix8 fix_div(fix8 a, fix8 b);

Parameters

a

Left operand in Q8.8.

b

Right operand in Q8.8.

Return value

Returns a Q8.8 quotient, or zero when b == 0.

Conditions and limits

The expression is ((a >> 4) * 256) / (b >> 4). A nonzero divisor must remain nonzero after the shift: do not pass positive raw values 1–15. The scaled numerator must also fit in 16 bits.

Usage example

result[3]=fix_div(768,512);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Dividing 3.0 by 2.0 yields 1.5 (raw 384). A separate check verifies the explicit zero-divisor return.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Scale the reduced-precision quotient back to 8.8 and return zero for b == 0.
Callers must also ensure (b >> 4) is nonzero; the explicit check only tests b.
The intermediate product must fit the compiler's integer arithmetic.

fix8 fix_div(fix8 a, fix8 b)
{
    if (b == 0) return 0;
    return (fix8)(((a >> 4) * 256) / (b >> 4));
}

Convert an integer coordinate or speed to Q8.8 so subsequent calculations can retain fractional parts.

Syntax

fix8 fix_from_int(s16 n);

Parameters

n

Integer to convert, from −128 through 127.

Return value

Returns the raw value n × 256.

Conditions and limits

fix8 is signed Q8.8: a raw value of 256 represents 1.0. Keep intermediate values and results within the 16-bit range.

Usage example

result[0]=fix_from_int(-3);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The example converts −3. The displayed −00768 is the raw Q8.8 result −768.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Convert an integer to signed 8.8 fixed point by moving it into the high byte.
The caller must keep the result within the representable 16-bit range.

fix8 fix_from_int(s16 n)
{
    return (fix8)(n << 8);
}

Interpolate from one Q8.8 value toward another using an eight-bit weight.

Syntax

fix8 fix_lerp(fix8 a, fix8 b, u8 t_q8);

Parameters

a

Left operand in Q8.8.

b

Right operand in Q8.8.

t_q8

Interpolation weight from 0 through 255.

Return value

Returns the approximated interpolated Q8.8 value.

Conditions and limits

The difference and weight are each shifted right by four bits. This gives 16 weight levels, so even 255 need not reach the endpoint. Keep b - a and the final result within 16 bits.

Usage example

result[4]=fix_lerp(0,1024,128);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

A weight of 128 between 0 and 4.0 yields 2.0 (raw 512). Weight 255 produces 3.75 (raw 960), demonstrating that the endpoint is not reached.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Interpolate toward b using a quantized Q0.8 weight. Both shifts discard low
bits, so small changes may vanish and a weight of 255 need not reach b.

fix8 fix_lerp(fix8 a, fix8 b, u8 t_q8)
{
    fix8 d;
    // The endpoint difference must fit s16 before the reduced-precision interpolation.
    d = (fix8)(b - a);
    return (fix8)(a + (fix8)((d >> 4) * (s16)(t_q8 >> 4)));
}

Multiply two Q8.8 values using a low-cost approximation.

Syntax

fix8 fix_mul(fix8 a, fix8 b);

Parameters

a

Left operand in Q8.8.

b

Right operand in Q8.8.

Return value

Returns the product in Q8.8.

Conditions and limits

Each operand is shifted right by four bits before multiplication, discarding four low bits from each. This is less precise than a full 16-by-16-bit product. fix8 is signed Q8.8: a raw value of 256 represents 1.0. Keep intermediate values and results within the 16-bit range.

Usage example

result[2]=fix_mul(384,512);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Multiplying 1.5 by 2.0 yields 3.0 (raw 768). The program also checks the quantization case where raw 271 multiplied by raw 271 yields 256.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Approximate 8.8 multiplication by discarding four low bits from each operand
before multiplying. This trades precision for a smaller intermediate product.

fix8 fix_mul(fix8 a, fix8 b)
{
    return (fix8)((a >> 4) * (b >> 4));
}

Extract an integer coordinate from Q8.8 by discarding its fractional bits. Negative values round toward negative infinity.

Syntax

s16 fix_to_int(fix8 x);

Parameters

x

Q8.8 value to convert to an integer.

Return value

Returns a signed integer.

Conditions and limits

fix8 is signed Q8.8: a raw value of 256 represents 1.0. Keep intermediate values and results within the 16-bit range.

Usage example

result[1]=fix_to_int(-384);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Passing raw −384 (−1.5) produces −2, displayed as −00002. A boundary check also confirms that raw −1 becomes −1.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Discard the eight fractional bits using a signed right shift.

s16 fix_to_int(fix8 x)
{
    return (s16)(x >> 8);
}

Find the magnitude of a signed 16-bit value.

Syntax

s16 kq_abs_s16(s16 v);

Parameters

v

Signed 16-bit value whose magnitude is needed.

Return value

Returns a nonnegative magnitude, except for the unrepresentable magnitude of −32768.

Conditions and limits

The positive magnitude 32768 does not fit in s16. Exclude −32768 when a nonnegative result is required.

Usage example

result[0]=kq_abs_s16(-123);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

The sample turns −123 into 123, as when measuring the magnitude of a coordinate difference.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math_limits.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math_limits.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Return the magnitude in s16. The most-negative s16 has no positive s16
representation and must be excluded by callers needing a nonnegative result.

s16 kq_abs_s16(s16 v)
{
    if (v < 0) return (s16)(0 - v);
    return v;
}

Restrict a coordinate or speed to an inclusive interval.

Syntax

s16 kq_clamp_s16(s16 v, s16 lo, s16 hi);

Parameters

v

Signed value to limit.

lo

Inclusive lower limit.

hi

Inclusive upper limit.

Return value

Returns lo below the interval, hi above it, or v within it.

Conditions and limits

Supply a valid interval with lo <= hi.

Usage example

result[3]=kq_clamp_s16(25,-10,10);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Clamping 25 to −10…10 yields 10. Checks also cover −11→−10 at the lower edge and 3→3 inside the interval.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math_limits.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math_limits.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Clamp to an inclusive interval; callers must provide lo <= hi.

s16 kq_clamp_s16(s16 v, s16 lo, s16 hi)
{
    if (v < lo) return lo;
    if (v > hi) return hi;
    return v;
}

Select the larger of two signed 16-bit values.

Syntax

s16 kq_max_s16(s16 a, s16 b);

Parameters

a

First signed value to compare.

b

Second signed value to compare.

Return value

Returns the selected operand.

Conditions and limits

Comparison is signed. Equal operands produce that same value; neither input is modified.

Usage example

result[2]=kq_max_s16(-7,4);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Comparing −7 and 4 yields 4. Negative results are displayed with a minus sign.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math_limits.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math_limits.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Select the larger signed value.

s16 kq_max_s16(s16 a, s16 b)
{
    if (a > b) return a;
    return b;
}

Select the smaller of two signed 16-bit values.

Syntax

s16 kq_min_s16(s16 a, s16 b);

Parameters

a

First signed value to compare.

b

Second signed value to compare.

Return value

Returns the selected operand.

Conditions and limits

Comparison is signed. Equal operands produce that same value; neither input is modified.

Usage example

result[1]=kq_min_s16(-7,4);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Comparing −7 and 4 yields -7. Negative results are displayed with a minus sign.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math_limits.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math_limits.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Select the smaller signed value.

s16 kq_min_s16(s16 a, s16 b)
{
    if (a < b) return a;
    return b;
}

Test whether a point lies in a rectangle, including its left and top edges.

Syntax

u8 kq_point_in_rect(s16 x, s16 y, KQRect r);

Parameters

x

Point X coordinate in the rectangle’s coordinate system.

y

Point Y coordinate.

r

Rectangle to test, passed by value.

Return value

Returns 1 inside and 0 outside.

Conditions and limits

Use positive dimensions and keep coordinate-plus-size sums representable as s16. Right and bottom edges are excluded. Zero-area rectangles are not explicitly rejected.

Usage example

result[1]=kq_point_in_rect(9,1,a);
for(gy=0;gy<11;gy++){for(gx=0;gx<15;gx++){
inside_a=kq_point_in_rect(gx,gy,a);inside_b=kq_point_in_rect(gx,gy,b);
tile=0;if(inside_a){tile=65;result[3]=result[3]+1;}if(inside_b)tile=66;if(inside_a && inside_b){tile=79;result[4]=result[4]+1;}
m_put(1+gx,2+gy,tile);__vramq_commit();__vramq_exec();
}}

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Each coordinate unit occupies one tile. Rectangles A at (1,1) and B at (5,4) are both 8×6. A-only cells show A, B-only cells show B, and the 4×3 overlap shows 12 O cells. A’s right edge x=9 is excluded. On CGB, A is red, B blue and O green.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_geometry.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_geometry.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Test a half-open rectangle: left/top edges are included, right/bottom excluded.
The coordinate-plus-size sums must remain representable as s16.

u8 kq_point_in_rect(s16 x, s16 y, KQRect r)
{
    if (x < r.x) return 0;
    if (y < r.y) return 0;
    if (x >= (s16)(r.x + r.w)) return 0;
    if (y >= (s16)(r.y + r.h)) return 0;
    return 1;
}

Test whether two axis-aligned rectangles overlap with positive area.

Syntax

u8 kq_rect_intersect(KQRect a, KQRect b);

Parameters

a

First rectangle, passed by value: x, y locate its top-left corner; w, h are its width and height.

b

Second rectangle in the same coordinate system as A.

Return value

Returns 1 for overlap and 0 for separation or mere edge contact.

Conditions and limits

Use positive dimensions and keep coordinate-plus-size sums representable as s16. Right and bottom edges are excluded. Zero-area rectangles are not explicitly rejected.

Usage example

result[0]=kq_rect_intersect(a,b);result[2]=kq_rect_intersect(a,touch);

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

Each coordinate unit occupies one tile. Rectangles A at (1,1) and B at (5,4) are both 8×6. A-only cells show A, B-only cells show B, and the 4×3 overlap shows 12 O cells. A’s right edge x=9 is excluded. On CGB, A is red, B blue and O green.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_geometry.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_geometry.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Test overlap using exclusive right/bottom edges; touching edges do not collide.
Require positive dimensions and edge sums that fit s16; zero-sized rectangles
are not explicitly rejected and may be reported as overlapping.

u8 kq_rect_intersect(KQRect a, KQRect b)
{
    if ((s16)(a.x + a.w) <= b.x) return 0;
    if ((s16)(b.x + b.w) <= a.x) return 0;
    if ((s16)(a.y + a.h) <= b.y) return 0;
    if ((s16)(b.y + b.h) <= a.y) return 0;
    return 1;
}

btn_down is an alias for input_down. Checks whether any selected button is currently held.

Test whether any button selected by mask is currently held.

Syntax

u8 btn_down(u8 mask);

Parameters

mask

One BTN_* mask or several joined with |. The test succeeds if any selected button matches; BTN_A | BTN_B does not require both. Mask 0 always gives 0. To require every button, compare (input_current() & mask) == mask.

Return value

Exactly 1 if any selected button matches the queried condition; otherwise 0. The return value is not a button mask.

Conditions and limits

The header defines an object-like macro that expands to the implementation name. Arguments, return values and state access are the same as the target; the alias adds no separate state or processing. Use input.h/input.c for input or system.h/system.c for frame services as shown in the complete example and build command.

Shared masks: BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80. A set bit means held. This layout applies to input_* on both GB and FC; raw FC pad functions use a different order.

Getters observe the most recent input_update() without polling, consuming an edge or advancing a repeat timer. Repeated getter calls in the same tick give the same answer. Calling input_update() twice while a button stays down clears its press edge on the second call.

input_down

Usage example

if (btn_down(BTN_A)!=0) held_ticks++;

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program demonstrates the difference between held state, a new press, release and automatic repeat. Hold A for 40 updates, then release it. FIRST DOWN, FIRST PRESS and FIRST REPEAT are 1; FIRST CURRENT is 16. HELD TICKS is 40, PRESS COUNT is 1 and REPEAT COUNT is 5. On release, RELEASE is 1, LAST CURRENT is 0 and LAST PREVIOUS is 16. FAILED CHECKS must be 0. Holding A for a different duration changes the counts; the program checks the repeat timing against the duration it actually observed.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\input.c .\kitaq-docs\samples\api-examples\fc\input_aliases.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\input_aliases.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm --no-cache

#define btn_down input_down

u8 input_down(u8 mask) { return (u8)((kq_input_keys & mask) != 0); }

btn_pressed is an alias for input_pressed. Checks whether any selected button became pressed in the latest input update.

Test whether a masked button changed from released to pressed in the latest input update.

Syntax

u8 btn_pressed(u8 mask);

Parameters

mask

One BTN_* mask or several joined with |. The test succeeds if any selected button matches; BTN_A | BTN_B does not require both. Mask 0 always gives 0. To require every button, compare (input_current() & mask) == mask.

Return value

Exactly 1 if any selected button matches the queried condition; otherwise 0. The return value is not a button mask.

Conditions and limits

The header defines an object-like macro that expands to the implementation name. Arguments, return values and state access are the same as the target; the alias adds no separate state or processing. Use input.h/input.c for input or system.h/system.c for frame services as shown in the complete example and build command.

Shared masks: BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80. A set bit means held. This layout applies to input_* on both GB and FC; raw FC pad functions use a different order.

Getters observe the most recent input_update() without polling, consuming an edge or advancing a repeat timer. Repeated getter calls in the same tick give the same answer. Calling input_update() twice while a button stays down clears its press edge on the second call.

input_pressed

Usage example

if (btn_pressed(BTN_A)!=0) {
        press_count++; seen_press=1;
        first_down=btn_down(BTN_A); first_press=btn_pressed(BTN_A);
        first_repeat=btn_repeat(BTN_A);
        first_current=input_current(); // Only A held: BTN_A, or decimal 16.
        first_previous=input_previous(); // No buttons in the preceding sample: 0.
        if (first_down!=1 || first_press!=1 || first_repeat!=1) failures++;
        if (first_current!=BTN_A || first_previous!=0) failures++;
        if (btn_down(BTN_A|BTN_B)!=1 || btn_down(0)!=0) failures++;
    }

This is a calling fragment. Follow the stated initialization and buffer requirements before using it in a complete program.

Expected result

This program demonstrates the difference between held state, a new press, release and automatic repeat. Hold A for 40 updates, then release it. FIRST DOWN, FIRST PRESS and FIRST REPEAT are 1; FIRST CURRENT is 16. HELD TICKS is 40, PRESS COUNT is 1 and REPEAT COUNT is 5. On release, RELEASE is 1, LAST CURRENT is 0 and LAST PREVIOUS is 16. FAILED CHECKS must be 0. Holding A for a different duration changes the counts; the program checks the repeat timing against the duration it actually observed.

Complete example program

Build command

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\input.c .\kitaq-docs\samples\api-examples\fc\input_aliases.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\input_aliases.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm --no-cache

#define btn_pressed input_pressed