Web64 C Compiler User Manual

Version: 2026-09-29

Copyright (c) 2026 Mika Jussila, Siteledger Solutions Oy

This manual separates the Web64 C compiler and SDK reference from the broader IDE manual. The larger IDE workflow context remains in Web64 IDE User Manual.

Web64 C compiler and virtual headers

Web64 IDE includes the browser-native Web64 C compiler. Existing projects that omit compiler-profile fields retain the web64-c-v0.1 dialect and web64-static-v0 ABI byte-for-byte where no bug fix applies. New C projects use the web64-c90 freestanding dialect and web64-stack-v1 ABI. Strict ansi-c90 is also available when Web64 language extensions should be diagnosed. This manual describes all three profiles and their shared C64 lowering, hardware, asset, multi-translation-unit, and mixed C/assembly contracts.

The C compiler is not cc65. It does not use cc65 object files, linker scripts, or a native toolchain. Web64 C lowers supported C modules into Web64 assembler-compatible source, then the existing browser-local assembler produces the PRG, symbols, line maps, diagnostics, and memory ranges.

When the optional Generated Assembly workspace is enabled and opened, the IDE exposes that lowering result as structured, read-only instruction rows with encoded bytes, addresses, and original C source provenance. Display formatting and lookup indexes are created lazily for the active compile revision; enabling the setting alone does not add projection work to live C editing. Source breakpoints use stable lowering provenance where available and are remapped after regenerated addresses move. See Generated Assembly machine view for the complete workflow and machine-breakpoint distinction.

C project model

A C project is made from virtual project records, not host paths. Typical records are:

main.c
include/game.h
assets/generated.h
assets/sprites/player.spr
assets/maps/level1.map

The build graph classifies .c files as C modules, .h files as C headers, assembly files as assembly modules, and asset files as binary or generated records. Build Targets select the exact C and assembly translation units linked into each PRG. C modules are ordered before assembly modules so generated C labels, compiler-created ABI slots, and handwritten assembly labels share the final assembler symbol namespace.

Web64 C emits a startup label that calls the configured C entry function. A Build Target rooted at main.c does not need a placeholder assembly translation unit. Legacy/single-target C projects may still contain the IDE's root main.asm; leave that file empty unless it intentionally provides assembly support. If a mixed project deliberately supplies its own assembly startup, call the C entry yourself, for example jsr _main for a C function named main, and select only the intended startup module in the target.

C labels are emitted with underscore names. A C function named main becomes _main in assembly. Direct calls to normal C functions emit jsr _name; calls to names that already start with asm_ are treated as direct assembly labels.

C configuration

The new-project C configuration is:

{
  "enabled": false,
  "dialect": "web64-c90",
  "abi": "web64-stack-v1",
  "entry": "main.c",
  "includePaths": ["include", "assets"],
  "stdout": "screen",
  "stdin": "keyboard",
  "runtimeProfile": "freestanding",
  "stack": { "size": 512, "address": null },
  "compilerBackend": "web64-native"
}

Persisted projects without dialect or abi fields normalize to web64-c-v0.1 plus web64-static-v0; this is the compatibility profile. web64-c90 enables the C90 translation phases and Web64 extensions. ansi-c90 uses the same backend but reports extensions such as //, _fastcall, _Bool, and inline assembly as errors. web64-stack-v1 supplies recursive automatic frames, variadic layout, and wide parameters/returns. The stack region defaults to the highest safe RAM below I/O and is included in overlap diagnostics and the memory-layout report.

Supported stdout backends are screen, kernal, debug, and none. Supported stdin backends are keyboard, kernal, debug, and none. Use none for freestanding routines that do not need the tiny runtime I/O shims. runtimeProfile currently supports tiny and freestanding.

Compatibility and non-regression contract

The C90 rollout does not route compatibility projects through the stack ABI. A program accepted by web64-c-v0.1 keeps its established semantics, generated bytes, size, cycle ceilings, and helper closure unless a classified compiler bug fix requires a change. Golden assembly/PRG fixtures cover fixed-point operations, arrays, asset access, loops, C/assembly calls, raster kernels, and generated-table consumers. Integer-only and fixed-only projects may not gain floating, stack, recursion, or generic arithmetic helpers.

The executable release gates compare generated output and classify every intentional difference as improved, equivalent, or justified. They also exercise real project classes and fail when code-size, deterministic-cycle, runtime-dependency, or zero-page ownership ceilings regress. C90 code uses the same specialized immediate, direct-index, hardware-register, and fixed-point lowering whenever standard semantics permit it.

Supported C subset

Web64 C is a freestanding implementation with an explicit 6502 data model. Its implemented C90-profile surface includes:

• Fully lowered 8-bit and 16-bit integer scalars, _Bool, 16-bit pointers, constant-valued enum declarations, typedef-backed SDK aliases, and fixed-layout structs/unions supported by Web64 aggregate metadata.
• File-scope globals, parameters, prototypes, extern, and static internal linkage. Automatic locals may be declared in the function body, nested compound statements such as if, while, do, switch, and standalone blocks, or a for initializer. Inner blocks and for scopes may shadow outer names; each declaration receives a distinct deterministic function-owned storage label. Static functions and objects receive module-private assembler labels, while conflicting definitions in the same scope are errors.
• Scalar assignments, increments/decrements, casts, integer promotion, arithmetic, comparisons, bitwise/logical expressions, fixed-size multidimensional arrays with constant/runtime indexes, sizeof, supported member access, and typed pointer reads and writes.
• Direct declared calls, supported bundled-runtime calls, return, if/else, while, do/while, for, break, continue, and Web64-native switch dispatch with case fallthrough.
• _fastcall for the documented register-call shapes, the compatibility static-slot ABI, and the C90 software-stack ABI with recursive automatic storage, caller cleanup, variadic arguments, named function-pointer objects, and hidden-pointer wide returns.
• const, volatile, and register qualifiers on supported declarations. C volatile objects are marked in generated assembly so optimizer passes preserve observable accesses.
• C90 trigraph replacement, line splicing, comment replacement, preprocessing tokens, line-preserving conditional groups, object-like and function-like macros, #, ##, #define, #undef, include guards, and active #error directives.
• Governed #pragma diagnostics, diagnostic-only __attribute__((unused)) and __attribute__((noreturn)), and inline assembly through asm("..."), asm volatile("..."), or __asm__("...").
• Bundled and project-local virtual includes plus decimal, 0x hexadecimal, and dollar-sign hexadecimal integer constants.

Local names follow lexical C scope and their initializers execute whenever control reaches the declaration. Under web64-stack-v1, automatic objects occupy recursive software-stack frames. Under web64-static-v0, each declaration retains its legacy static function-owned slot and generated functions remain non-reentrant.

Undeclared identifiers and undeclared custom functions are errors. Calls to the bundled runtime and names beginning with asm_ retain their legacy implicit-call behavior for existing projects. Unsupported statements, types, signatures, and annotations produce diagnostics instead of being silently accepted.

Constant operands and constant conditions

See 6502 cost model and hot-loop performance for choosing between inexpensive frame work and acceptable setup work.

Typed byte expressions with a compile-time constant use specialized lowering for +, -, &, |, and ^. Commutative operations accept the constant on either side and use a 6502 immediate operand; value - constant uses immediate SBC. constant - value uses an order-preserving sequence and may need one byte temporary, but it avoids the generic stack spill. The constant may be a literal, numeric define, or folded constant expression. This lowering also applies when the dynamic operand is a function result, so it does not use the stack or a zero-page temporary merely to hold the constant. Byte identities such as value + 0, value - 0, value | 0, value ^ 0, and value & 0xff retain evaluation of value but omit the redundant arithmetic instruction.

Constant conditions are folded when the typed expression is side-effect-free. while (true) therefore emits the loop body and back edge without loading and testing 1. Calls, volatile accesses, and other observable expressions are still evaluated; for example, while (rand()) retains the call and conditional branch.

With the temporary/register optimization pass enabled, eligible byte compound updates at a fixed address plus an unsigned byte index use absolute indexed addressing. This includes |=, &=, ^=, += and -= with foldable constant offsets. Index side effects are evaluated once, typed narrowing and 16-bit address wrapping are preserved, and volatile targets still receive exactly one read and one write. Signed/wide indexes and unproven mutable pointers retain the general path.

Non-literal 16-bit comparisons now materialize and compare both operand bytes for ==, !=, <, <=, >, and >=. Signed ordering biases both high bytes before comparison, while unsigned ordering compares them directly. Eight-bit integer operands receive the target's normal signed int promotion before mixed-width ordering, including int16_t with uint8_t and int8_t with int16_t. Compound word operands such as target > position + 256 carry through the high byte correctly. Byte-only comparisons retain their immediate and single-byte fast paths.

With the temporary/register optimization pass enabled, side-effect-free words in fixed storage can be consumed directly instead of being copied to temporary words. This includes non-volatile globals, statics and direct packed-struct fields in comparisons, truth tests, word returns and call arguments. A comparison uses this shortcut only when both operands are safe; calls, pointer dereferences, volatile objects and live stack-frame references retain their conservative evaluation paths. Ordinary call arguments still enter their normal snapshot or caller-owned slot before the next argument is evaluated. Volatile word values read both bytes once in address order, including tests against zero. Explicit narrowing and signed casts retain their typed meaning, and !/!! tests the complete operand even when its result is stored in one byte.

For example:

while (true) {
    *((uint8_t*)VIC_BORDER) = rand() & 0x0f;
}

lowers to the following core sequence. Generated label suffixes vary by source location.

__web64_c_while_...:
    jsr _rand
    and #0xf
    sta 0xd020
    jmp __web64_c_while_...

The immediate-operand and constant-condition rules are part of typed C lowering and do not require enabling an optional optimizer pass.

6502 cost model and hot-loop performance

How do I optimize this per-frame C code in Web64? Start with the target and the actual hot path: Web64-C executes on the Commodore 64's MOS 6510, a 6502-family CPU with an approximately 1 MHz budget, not a modern host CPU. Frame/runtime work is cycle constrained. VIC-II display activity and IRQ work share that budget; the full frame is not all available to application code. The emulator host being fast does not make generated C64 instructions free.

For hot-loop optimization, establish which work repeats before changing arithmetic.

The CPU has no native hardware integer multiply, divide or modulo instructions. Repeated non-power-of-two operations such as value % 37, % 12, / 24 or % 10 may therefore be expensive in a hot loop. They are valid C, not errors, and a one-time setup calculation is often entirely reasonable. Do not mechanically remove every division or change a game's ranges merely to replace % 12 with & 15; that changes the result.

Current Web64-C behavior matters more than a generic rule of thumb:

• Constant expressions can fold at compile time. In supported typed 16-bit integer

paths, multiplication by zero, one, minus one or powers of two lowers inline. Some other constant multiplies use budget-checked shift/add chains; a constant multiply is not a promise of one instruction or of a helper call.

• Unsigned division/remainder by a constant power of two lower to logical shifts

or masks. Signed division needs truncation-toward-zero bias, and signed remainder retains the dividend's sign. A signed x / 8 is not generally interchangeable with x >> 3, nor is signed remainder generally interchangeable with a mask.

• Other integer division/remainder operations can retain dependency-selected

arithmetic helpers. Width, signedness, expression context and optimizer settings affect the output. Do not assume arbitrary constant divisors get a cheap reciprocal-multiply transformation. Inspect the actual Generated ASM.

• Fixed-point helpers have their own documented specializations; use their

fixed-point contracts, not integer substitutions.

For repeated bounded transforms, consider a lookup table if its RAM/ROM footprint is justified. An incremental counter or cached result can avoid recomputing the same quotient, digit conversion, layout or address each frame. For example, a counter already constrained to 0..11 can wrap with increment/compare/reset; that is not a general replacement for arbitrary value % 12. Preserve exact semantics, ranges, overflow behavior and side effects before measuring a change.

Separate cold initialization/setup from hot per-frame work. Avoid redrawing unchanged HUD values or rebuilding every screen/color RAM cell each frame; update dirty cells or changed rows, and keep animation updates separate from static layout. Use uint8_t, int8_t, uint16_t and wider types deliberately. Web64's int is 16-bit; byte storage does not prevent C integer promotion. Signedness and intermediate width can change both results and cost.

Expensive initialization may be acceptable, but visible partial construction usually is not. Prepare state before revealing it, keep the old screen visible while safe independent data is prepared, or deliberately blank the display during a transition and restore it only when screen, colors and charset state agree. Choose a strategy compatible with the project's VIC bank, memory ownership and interrupts. An off-screen buffer is optional, not a universal double-buffering requirement; account for the memory and reveal/copy cost. Do not blank or disable interrupts indiscriminately just to hide slow per-frame work.

Measure important paths with Generated ASM and the opt-in Cycle / Raster Profiler. Distinguish observed instruction/stall costs from inferred routine attribution, use the matching build, and compare representative branch paths. Manual cycle counts must include branch/page-cross behavior and display/IRQ interference where relevant. Source-level operation counts alone are not performance measurements. MCP can discover this guidance and inspect generated/build contracts; profiling and emulator execution remain normal human IDE actions, not new MCP controls.

Switch statements

Web64 C supports compact integer switch dispatch for state machines, menus, and asset-kind routing. The compiler emits a linear compare/branch sequence and generated labels such as __web64_c_case0_... and __web64_c_switchend_...; it does not pull in the cc64 runtime switch helper or cc65 code movement.

uint8_t mode;
uint8_t color;

void main(void) {
    switch (mode) {
        case 0:
            color = 6;
            break;
        case 1:
            color = 14;
            break;
        default:
            color = 1;
            break;
    }
}

Case labels must resolve to numeric constants or defines. Duplicate case values and duplicate default labels are errors. Fallthrough is preserved when a case omits break.

Pragmas, attributes, and calling conventions

Web64 C uses a registry for pragmas and attributes so source annotations either map to a known Web64 behavior or produce a stable diagnostic.

Supported or recognized forms are:

Unknown attributes are errors. This is intentional: Web64 C should not suggest that cc65 or hosted C annotation semantics are active unless the browser-local compiler has executable support for them.

Compile-time C64 string encoding

The setting applies to subsequent string literals, including literal call arguments, and can be reset with #pragma charset("ascii"). It changes emitted bytes, not the VIC-II font selection or the bytes received from the keyboard.

The two explicit mixed modes match the assembler for printable source characters. In screencode_mixed, @ is screen byte $00, [, \\, ], ^ are $1b-$1e, and _ is $64. Spaces and digits retain their familiar bytes. The glyph shown for a punctuation byte depends on the selected C64 charset; these modes are byte-oriented C64 mappings, not a Unicode font translator.

Numeric escapes such as \x41, \xff, \101 and \0 are literal target bytes in every mode. Named control escapes such as \n, \r and \t also retain their C byte values (10, 13 and 9). Escaped printable punctuation, including \\, still follows the selected character mapping. High-byte literals have the same representation in arrays and pooled call arguments; they are not expanded to UTF-8.

#pragma charset("screencode_mixed")
const char title[] = "Document Editor";
const char rows[] = "Open\377Save\377Close"; /* application-defined $ff separator */
#pragma charset("ascii")

The generated arrays already contain screen codes, so no startup loop or conversion routine is linked. Only use a separator such as $ff if the receiving routine explicitly implements it. C hex escapes consume all following hex digits: \xffClose includes the C in the escape. The fixed three-digit octal form \377 avoids that ambiguity. In mixed screen codes lowercase j is byte 10, so a screen-text routine cannot also treat byte 10 as an unambiguous line delimiter. Likewise, @ produces byte 0; a normal NUL-terminated C string routine stops there. Use a length-aware renderer when all screen-code values must be displayable.

Quoted character constants such as 'A', 'a' and '\n' are not affected. Unknown encoding names produce explicit errors; the C64 encoding modes also reject source characters beyond their byte-oriented mapping. The directive is #pragma charset, not #pragma charmode.

Adjacent string literals compose into one string in arrays and ordinary or nested call arguments, including literals produced by macros. Each fragment is decoded separately before composition, so "\xff" "Close" emits the exact $ff separator followed by the encoded word; the C cannot become part of the preceding hex escape. Whitespace, comments and source-line breaks may separate fragments without inserting bytes. This permits long messages to remain readable in source without a runtime concatenation step.

Include resolution

C includes are virtual includes. These forms are accepted:

#include <stdint.h>
#include <c64.h>
#include "include/game.h"
#include "assets/generated.h"

The resolver rejects absolute host paths such as C:/..., /home/..., \\server\..., and file: URLs. Put headers into the Web64 virtual filesystem and include them by project-relative path.

The C90 profiles apply trigraph replacement, escaped-newline splicing, comment replacement, conditional preprocessing, macro replacement, stringification, token pasting, and tokenization before the specialized declaration parser. Conditional groups preserve line positions for diagnostics, and bundled headers use include guards so repeated or transitive includes do not duplicate declarations. Host compiler extensions and host filesystem preprocessing are never imported implicitly.

Function-like statement macros can use the usual do { ... } while (0) form. They remain a single controlled statement in if (...) MACRO(...); else ..., while and for bodies. Macro authors must still avoid evaluating an argument more than once when that argument can have side effects; wrapping statements does not itself make repeated argument use safe.

assets/generated.h is generated from project asset records at compile time. It exposes deterministic C-safe start/end labels, _size constants, and numeric _kind constants. Asset records keep their browser-local generated-record placement metadata; no native linker script or object segment is introduced.

Bundled virtual headers

Web64 C bundles a small read-only SDK. These headers are resolved from web64://c/include/... before project-local include lookup, except assets/generated.h, which is regenerated from the current project asset records during the build.

The headers are intentionally compact. Every function declared by the bundled standard-library headers above has either an executable dependency-selected runtime implementation or the documented compiler lowering. Including them does not make the full cc65 or hosted C library available. Runtime-owned parameter slots are emitted once for a whole multi-module build, so repeated guarded includes and calls from multiple translation units do not create duplicate labels. The Web64 SDK tree opens headers as read-only web64://c/include/... documents. It also exposes bundled assembler .inc files as read-only web64://asm/include/... documents in assembly and mixed projects. Both document types retain per-file cursor/scroll state, support navigation and search, and can be copied into include/ when a project-specific editable variant is needed.

Standard headers use extern function declarations because the implementation is outside the header. extern does not assign a fixed address. Calling memcpy, for example, selects web64-runtime/string.asm; including string.h without calling a string function adds no string runtime code. libc.h is retained for source compatibility as an aggregate include, but new code may include the specific standard headers it uses.

The memory helpers use indexed 256-byte page kernels with bounded tails. memset, memcpy, and memmove preserve zero-length behavior and return the original destination; memmove retains forward/backward overlap safety. Each helper links only its own parameter storage and reachable implementation, so memcpy no longer accidentally includes memset. Public declarations and ordinary C calling conventions are unchanged. Native Web64 game libraries retain their separate exact-width _web64_rt windows and direct assembly entry points.

c64lib compatibility from C

c64lib headers are available only when the matching compatibility module is selected for the active Build Target. Dependencies are automatic: Text selects Common and Chipset; copper64 selects Common and Chipset; Magic Desk selects Common and Chipset; and 64spec selects Common and Text. A missing module produces a build diagnostic instead of silently accepting a declaration that cannot link. Merely selecting a module or including one of its headers adds no runtime bytes; a routine is linked only when referenced.

The C-facing routines use the target's canonical Web64 ABI. New C/c64lib targets default to web64-stack-v1 unless the target explicitly selects another ABI. Legacy web64-static-v0 targets keep their existing static parameter slots. Web64 does not introduce a second c64lib calling convention. Handwritten optimized routines that use another register contract require a thin assembly wrapper.

#include <stdint.h>
#include <c64.h>
#include <c64lib/common.h>
#include <c64lib/chipset.h>

void main(void) {
    c64lib_fill_screen((void*)0x0400, 32);
    c64lib_set_vic_bank(C64LIB_BANK_0);
    VIC->border_color = COLOR_BLUE;
    while (1) {
    }
}

The copper64 C list uses immutable four-byte C64libCopperEntry records. Call c64lib_disable_cia_interrupts() before c64lib_copper_start() when CIA interrupt sources would conflict. The V3 dispatcher installs through the KERNAL IRQ vector and implements all 22 handler IDs with direct dispatch. Timing contracts distinguish double-IRQ stabilized handlers, line-sequenced handlers, byte-semantic handlers, and PAL/NTSC raster-transition handlers; full raster bars remain badline-sensitive. C callbacks from a copper JSR entry must go through the assembly web64_c64lib_guarded_c_callback wrapper; arbitrary C runtime calls are not implicitly IRQ-safe.

The complete classification, source pins, migration rules, limitations, and license notices are in Web64-native c64lib compatibility. The machine-readable release contract is c64lib-compatibility-v3.json.

Dependency-linked disk I/O

Include <web64/disk.h> for high-level disk access. Literal names can use WEB64_DISK_NAME("NAME"), which supplies both pointer and byte length without a runtime strlen.

#include <stdint.h>
#include <web64/disk.h>

uint8_t load_level(void) {
    return web64_disk_load(WEB64_DISK_NAME("LEVEL1"), 8, 0x4000);
}

uint8_t save_game(void) {
    return web64_disk_save(WEB64_DISK_NAME("SAVEGAME"), 8, 0x5000, 0x5100);
}

web64_disk_load returns the KERNAL status and records the loaded end address for web64_disk_last_end. web64_disk_save saves [start_address, end_address). web64_disk_require verifies a generated USR marker before a level load. web64_disk_request writes an assisted swap request but does not replace marker verification in portable code.

Streaming I/O uses a caller-chosen logical file and explicit device number. A program can keep its application disk on device 8 while opening document files on device 9; logical file numbers and device numbers are independent. Open the channel, read or write bytes, then close it. web64_file_read stores a byte only after successful channel selection and input. WEB64_DISK_STATUS_EOI can accompany the final valid byte and is not equivalent to device-not-present.

uint8_t value;
uint8_t status = web64_file_open(WEB64_DISK_NAME("TABLE,S,R"), 2, 8, 2);
if (status == WEB64_DISK_OK && web64_disk_last_error() == 0) {
    /* Check this drive's DOS channel 15 before treating OPEN as success. */
    do {
        status = web64_file_read(2, &value);
        if (web64_disk_last_error() != 0) break;
        if (status != WEB64_DISK_OK && status != WEB64_DISK_STATUS_EOI) break;
        /* value is valid here, including on the final EOI byte */
    } while (status == WEB64_DISK_OK);
}
web64_file_close(2);

Native disk errors have three independent domains; check all relevant domains before adopting data or reporting a successful save:

• The existing API return is unchanged: READST transport flags, a received byte, or the loaded end address, according to the function.
• uint16_t web64_disk_last_error(void) and uint16_t cbm_k_last_error(void) expose separate high-level-disk and direct-CBM KERNAL-call results. Zero means carry clear; a failure is $0100 | A. Bit 8 distinguishes every carry-set failure, including STOP with accumulator zero. The low byte is the original KERNAL accumulator, not a READST flag.
• The responding drive's DOS channel 15 reports filesystem results such as 26 write-protected, 62 file not found, 63 file exists and 72 disk full. KERNAL OPEN can succeed with READST zero while DOS reports file not found. READST or the last-error accessor alone is therefore not a filesystem-success test.

The high-level latch is replaced by load/save/require/file-open/file-read/file-write operations. The direct-CBM latch is replaced by OPEN, CHKIN, CHKOUT, CHRIN, CHROUT, LOAD and SAVE. Each family is independent. READST, last-error accessors, CLOSE and CLRCHN do not erase the prior checked call error; cleanup has no defined KERNAL carry-error result. Read the relevant latch immediately after the operation, before another checked operation in that family. Failed input does not publish an error code as file data. On successful input, READST EOI ($40) still accompanies a valid final byte.

For printer output, check READST after transfer and final cleanup as well as after OPEN; the KERNAL carry-error accessor alone does not report printer sink failures. Emulated output backends retain write, flush and close failures. In KERNAL-trap mode, READST exposes even errors discovered only while closing the host output file, and a new job can recover after the sink is corrected. These failures are not drive DOS error numbers.

Virtual IEC has a remaining limitation: a host sink failure discovered only at CLOSE can leave guest READST zero, and merely changing the output path after a bus transfer failure does not reinitialize the bus. Zero READST therefore does not universally prove that printer output was persisted. A successful channel CLOSE is also not a page-eject command: printer-model controls and finishing/capturing a partially printed page are separate concerns. No browser printer capture/download interface is implied by the KERNAL wrappers.

web64_file_read and web64_file_write select the logical channel on each call and leave it selected. For a measured streaming workload, direct <cbm.h> calls can select once and transfer multiple bytes; check each transfer, then call CLRCHN before returning to keyboard/default-screen I/O. GETIN reads the currently selected input, not necessarily the keyboard. KERNAL IEC transfers are synchronous.

For recoverable document replacement, write a distinct unused temporary file, close it, inspect DOS status and verify its complete contents. Rename the old file to a distinct unused backup, then promote the verified temporary file. Check DOS status after each rename and preserve recoverable names on failure. This is not atomic replacement: power loss can leave the old document under its backup name. Do not silently scratch a user's existing temporary/backup file or use destructive overwrite to bypass a disk-full error. Keep the active document unchanged until a separately staged load has passed format, capacity, content and EOF validation.

Include <cbm.h> for direct KERNAL control when the high-level contract is not suitable. Its wrappers preserve stable C signatures while calling the ROM vectors. The linker emits only referenced wrappers and their parameter slots. Disk development metadata never consumes C64 program memory unless the program includes and calls the corresponding API.

Web64 fixed-point math

web64/fixed.h provides the browser-native Web64 fixed-point math surface. The public storage types are ordinary integer-backed C types so they can live in globals, structs, arrays, project files, generated assembly, and debugger metadata without a native object ABI.

Common 8.8 constants and conversions are macros. They do not pull fixed runtime modules by themselves.

For a typed uint8_t or int8_t source, WEB64_FIX8_FROM_INT is recognized as byte placement rather than emitted as a shift sequence. The source byte becomes the integer byte and the fraction byte is cleared; the source is loaded first so assigning through overlapping storage remains correct:

    lda source
    sta destination+1
    lda #0
    sta destination

Implementation-backed 8.8 helpers are dependency-selected. Calling one helper pulls only the runtime module family it needs.

The header also provides short 8.8 aliases for these implementation-backed helpers: f8_mul_round, f8_div, uf8_mul, uf8_div, f8_lerp, f8_abs, f8_min, f8_max, f8_clamp, f8_add_sat, f8_sub_sat, f8_sin, f8_cos, v2f8_add, v2f8_sub, v2f8_scale, and m2d_int. These are preprocessor aliases to the web64_* names, so they keep the same ABI, semantics, and runtime dependency selection. The f8/uf8 prefixes are reserved for the current 8.8 tier; future 16.16 helpers can use distinct 16.16 names.

Signed multiply truncates toward zero from the signed widened product. web64_fix8_mul_round rounds nearest half away from zero. Unsigned multiply selects the middle product bytes, equivalent to (a * b) >> 8. Division uses a widened numerator equivalent to a * 256 / b; dynamic fixed division by zero returns 0, while constant zero divisors in ratio macros are diagnostics. Overflow wraps for ordinary fixed storage and wrapping helpers; use the saturating helpers when clamp-to-range behavior is wanted. web64_fix8_lerp(a, b, amount) uses amount/256, so amount=255 is close to b but not exactly b.

The standard trig table is a deterministic 256-entry signed 8.8 full-wave sine table. web64_sin8(angle) returns the table value. web64_cos8(angle) uses the same table with a 64-unit phase offset. The exact endpoints include web64_sin8(64) == 0x0100, web64_sin8(192) == 0xff00, web64_cos8(0) == 0x0100, and web64_cos8(128) == 0xff00.

The editor's Insert > Table and Insert > Matrix tools import the same canonical quantizer used to build this compiler table. Signed and unsigned 8.8 output therefore uses identical scale-256 words and nearest/half-away-from-zero rounding. A 256-step generated sine table with amplitude 1, center 0, phase 0, and web64_fix8_8 output is bit-for-bit identical to the compiler's web64_sin8 table. Generated cyclic tables exclude the repeated turn endpoint, matching web64_angle8 values 0..255. These tools perform offline source generation only; they do not add runtime helpers, hidden assets, or program-memory metadata.

Fixed 16.16 support is intentionally smaller in v1. Use the WEB64_FIX16_* constants, integer/ratio conversion macros, floor/to-int/fraction macros, and wrapping add/sub macros for storage and constant-scale data. There are no public 16.16 multiply/divide helper names until executable 6502 helpers and differential tests exist.

Use named helpers for fixed multiply and division. Direct fixed-point operators such as web64_sin8(phase) * radius are rejected by the v1 compiler with c-unsupported-fixed-point-operator; write the operation explicitly:

#include <web64/fixed.h>

web64_fix8_8 x = WEB64_FIX8_FROM_INT(120);
web64_fix8_8 velocity = WEB64_FIX8_FROM_RATIO(3, 2);

void step(void) {
    x = web64_fix8_add_wrap(x, velocity);
    *(uint8_t*)0xd000 = WEB64_FIX8_TO_INT(x);
}

#include <web64/fixed.h>

web64_angle8 phase;
web64_fix8_8 radius = WEB64_FIX8_FROM_INT(24);
web64_fix8_8 offset;

void step(void) {
    phase = phase + 2;
    offset = web64_fix8_mul(web64_sin8(phase), radius);
    *(uint8_t*)0xd000 = 160 + WEB64_FIX8_TO_INT(offset);
}

The fixed-point optimizer has a gated specialization pass. Constant helper calls fold to direct word materialization. Typed dynamic 8.8 operations by 0, 1, -1, and positive or negative powers of two lower to word copies, negation, or shifts when the transformation preserves the helper contract; dynamic web64_fix8_abs lowers to a sign test plus two's-complement negate and retains the INT16_MIN wrap result. Signed right shifts add an explicit negative-value bias so multiply by a reciprocal power of two and divide by a whole power of two still truncate toward zero. Unsigned division by a reciprocal power of two lowers to a wrapping left shift. A zero identity is used only when the discarded operand has no side effects. The runtime helper is removed only when every surviving lowered call requires it. Fixed specialization no longer reparses source: typed lowering records the decision and final lowered imports drive exact runtime closure.

The public examples repository contains source-backed projects for this section: c-fixed-subpixel-scroll, c-fixed-sine-lerp, and c-fixed-motion. These are portable .web64proj records and are compiled by the fixed-point regression harness.

c64.h hardware definitions

c64.h is the main low-level C64 hardware header. It exposes the same hardware through three compatible forms:

• Numeric addresses such as VIC_BORDER for explicit pointer casts, inline assembly, and address arithmetic.
• Volatile register structures such as VIC->border_color, SID->voice1_control, and CIA1->pra.
• Typed matrix views such as C64_SCREEN_ROWS[row][column].

All hardware structure members are volatile. A read or write therefore remains an observable hardware access and is not removed or merged by the optimizer.

Memory map and typed memory views

c64_reg8_t is the common unsigned 8-bit register type. The memory structures are:

typedef unsigned char c64_reg8_t;

typedef struct c64_cpu_port_registers {
    volatile c64_reg8_t data_direction;
    volatile c64_reg8_t data;
} c64_cpu_port_registers;

typedef struct c64_screen_ram {
    volatile c64_reg8_t cells[1000];
} c64_screen_ram;

typedef struct c64_color_ram {
    volatile c64_reg8_t cells[1000];
} c64_color_ram;

The corresponding typed aliases are:

The character ROM shares addresses with I/O. Change the 6510 memory configuration before reading C64_CHAR_ROM_GLYPHS, then restore it before accessing VIC-II, SID, CIA, or color RAM.

VIC-II structure

c64_vicii_registers maps $D000-$D02E in hardware register order:

typedef struct c64_vicii_registers {
    volatile c64_reg8_t sprite0_x;
    volatile c64_reg8_t sprite0_y;
    volatile c64_reg8_t sprite1_x;
    volatile c64_reg8_t sprite1_y;
    volatile c64_reg8_t sprite2_x;
    volatile c64_reg8_t sprite2_y;
    volatile c64_reg8_t sprite3_x;
    volatile c64_reg8_t sprite3_y;
    volatile c64_reg8_t sprite4_x;
    volatile c64_reg8_t sprite4_y;
    volatile c64_reg8_t sprite5_x;
    volatile c64_reg8_t sprite5_y;
    volatile c64_reg8_t sprite6_x;
    volatile c64_reg8_t sprite6_y;
    volatile c64_reg8_t sprite7_x;
    volatile c64_reg8_t sprite7_y;
    volatile c64_reg8_t sprite_x_msb;
    volatile c64_reg8_t control1;
    volatile c64_reg8_t raster;
    volatile c64_reg8_t lightpen_x;
    volatile c64_reg8_t lightpen_y;
    volatile c64_reg8_t sprite_enable;
    volatile c64_reg8_t control2;
    volatile c64_reg8_t sprite_y_expand;
    volatile c64_reg8_t memory_setup;
    volatile c64_reg8_t interrupt_status;
    volatile c64_reg8_t interrupt_enable;
    volatile c64_reg8_t sprite_priority;
    volatile c64_reg8_t sprite_multicolor;
    volatile c64_reg8_t sprite_x_expand;
    volatile c64_reg8_t sprite_collision;
    volatile c64_reg8_t data_collision;
    volatile c64_reg8_t border_color;
    volatile c64_reg8_t background_color0;
    volatile c64_reg8_t background_color1;
    volatile c64_reg8_t background_color2;
    volatile c64_reg8_t background_color3;
    volatile c64_reg8_t sprite_multicolor0;
    volatile c64_reg8_t sprite_multicolor1;
    volatile c64_reg8_t sprite0_color;
    volatile c64_reg8_t sprite1_color;
    volatile c64_reg8_t sprite2_color;
    volatile c64_reg8_t sprite3_color;
    volatile c64_reg8_t sprite4_color;
    volatile c64_reg8_t sprite5_color;
    volatile c64_reg8_t sprite6_color;
    volatile c64_reg8_t sprite7_color;
} c64_vicii_registers;

VICII is a volatile c64_vicii_registers* at VIC_BASE ($D000); VIC is its shorter alias. Sprite X/Y members cover sprites 0-7. sprite_x_msb supplies bit 8 for all sprite X positions. control1, control2, and memory_setup control display mode, scrolling, raster bit 8, and VIC memory selection. Collision members are hardware collision latches.

Every VIC-II register also has a numeric address:

Convenience aliases preserve familiar naming:

The 16 VIC-II palette values are:

SID structures

c64_sid_voice_registers describes one seven-register voice and is useful when a routine receives or creates a pointer to a voice base:

typedef struct c64_sid_voice_registers {
    volatile c64_reg8_t freq_lo;
    volatile c64_reg8_t freq_hi;
    volatile c64_reg8_t pulse_lo;
    volatile c64_reg8_t pulse_hi;
    volatile c64_reg8_t control;
    volatile c64_reg8_t attack_decay;
    volatile c64_reg8_t sustain_release;
} c64_sid_voice_registers;

c64_sid_registers maps the complete SID block at $D400:

typedef struct c64_sid_registers {
    volatile c64_reg8_t voice1_freq_lo;
    volatile c64_reg8_t voice1_freq_hi;
    volatile c64_reg8_t voice1_pulse_lo;
    volatile c64_reg8_t voice1_pulse_hi;
    volatile c64_reg8_t voice1_control;
    volatile c64_reg8_t voice1_attack_decay;
    volatile c64_reg8_t voice1_sustain_release;
    volatile c64_reg8_t voice2_freq_lo;
    volatile c64_reg8_t voice2_freq_hi;
    volatile c64_reg8_t voice2_pulse_lo;
    volatile c64_reg8_t voice2_pulse_hi;
    volatile c64_reg8_t voice2_control;
    volatile c64_reg8_t voice2_attack_decay;
    volatile c64_reg8_t voice2_sustain_release;
    volatile c64_reg8_t voice3_freq_lo;
    volatile c64_reg8_t voice3_freq_hi;
    volatile c64_reg8_t voice3_pulse_lo;
    volatile c64_reg8_t voice3_pulse_hi;
    volatile c64_reg8_t voice3_control;
    volatile c64_reg8_t voice3_attack_decay;
    volatile c64_reg8_t voice3_sustain_release;
    volatile c64_reg8_t filter_cutoff_lo;
    volatile c64_reg8_t filter_cutoff_hi;
    volatile c64_reg8_t filter_resonance;
    volatile c64_reg8_t volume_filter_mode;
    volatile c64_reg8_t pot_x;
    volatile c64_reg8_t pot_y;
    volatile c64_reg8_t osc3_random;
    volatile c64_reg8_t env3;
} c64_sid_registers;

SID is a volatile c64_sid_registers* at SID_BASE. The first 21 registers are three identical seven-register voices. filter_cutoff_lo, filter_cutoff_hi, and filter_resonance configure the filter; volume_filter_mode combines master volume and filter mode bits. pot_x, pot_y, osc3_random, and env3 are readback registers.

Numeric SID addresses are:

Control-register bit constants are SID_GATE, SID_SYNC, SID_RING_MOD, SID_TEST, SID_WAVE_TRIANGLE, SID_WAVE_SAW, SID_WAVE_PULSE, and SID_WAVE_NOISE. Combine one or more waveform bits with gate/control bits using |.

CIA, keyboard, and joystick structure

c64_cia_registers maps either CIA at $DC00 or $DD00:

typedef struct c64_cia_registers {
    volatile c64_reg8_t pra;
    volatile c64_reg8_t prb;
    volatile c64_reg8_t ddra;
    volatile c64_reg8_t ddrb;
    volatile c64_reg8_t timer_a_lo;
    volatile c64_reg8_t timer_a_hi;
    volatile c64_reg8_t timer_b_lo;
    volatile c64_reg8_t timer_b_hi;
    volatile c64_reg8_t tod_10ths;
    volatile c64_reg8_t tod_seconds;
    volatile c64_reg8_t tod_minutes;
    volatile c64_reg8_t tod_hours;
    volatile c64_reg8_t serial_data;
    volatile c64_reg8_t interrupt_control;
    volatile c64_reg8_t control_a;
    volatile c64_reg8_t control_b;
} c64_cia_registers;

CIA1 and CIA2 are typed volatile c64_cia_registers* aliases at CIA1_BASE and CIA2_BASE. pra/prb are the two data ports, ddra/ddrb select input or output per bit, timer members form the two 16-bit timers, tod_* is the time-of-day clock, and the final four members handle serial I/O, interrupts, and timer control.

Every CIA register also has a numeric address:

The keyboard matrix aliases are KEYBOARD_COLUMN_PORT, KEYBOARD_ROW_PORT, KEYBOARD_COLUMN_DDR, KEYBOARD_ROW_DDR, and KEYBOARD_ACTIVE_MASK.

JOYPORT_1 and JOYPORT_2 expose the CIA port addresses used by the two joystick ports. The input masks are JOY_UP, JOY_DOWN, JOY_LEFT, JOY_RIGHT, and JOY_FIRE. Joystick bits are active-low: JOY_ACTIVE_LOW is zero and JOY_RELEASED_MASK has all five input bits set.

The direct port-2 predicates JOY2_UP(), JOY2_DOWN(), JOY2_LEFT(), JOY2_RIGHT(), and JOY2_FIRE() read CIA1->pra. The value predicates JOY_UP_P(v), JOY_DOWN_P(v), JOY_LEFT_P(v), JOY_RIGHT_P(v), and JOY_FIRE_P(v) test a previously sampled port byte. A true predicate means pressed.

KERNAL entry points

The header provides numeric entry addresses rather than C wrappers. Call them through a compatible assembly wrapper or a supported zero-parameter indirect call only when the KERNAL ABI matches:

The KERNAL routines use register parameters, carry/status results, and shared KERNAL state. Prefer the Web64 SDK or an explicit assembly wrapper for calls that require parameters; a raw C function-pointer cast does not synthesize the KERNAL register ABI.

Web64 helper headers

The helper headers combine compiler-recognized operations, macros, and dependency-selected runtime functions. They are intended for compact C64 projects and provide direct register, KERNAL, SID, disk, graphics, input, timing, and utility interfaces.

#include <stdint.h>
#include <joy.h>
#include <sprite.h>
#include <web64.h>

uint8_t joy;
uint8_t rnd;

void main(void) {
    clrscr();
    gotoxy(0, 0);
    cprintf("READY");

    sprite_enable(1);
    sprite_set_pos(0, 300, 100);
    sprite_set_color(0, VIC_COLOR_LIGHT_GRAY);

    joy = joy_read();
    rnd = random8();
    if (!(joy & JOY_FIRE)) {
        plot_pixel(0x0400, 42);
    }

    delay_frames(2);
    delay_ms(40);
}

plot_pixel(address, value) is byte-oriented in the current helper ABI: pass the target bitmap, screen, color, or other memory address explicitly. delay_ms() is frame-based and approximate.

VoidCall(addr) calls a zero-parameter void function at a literal, generated, or runtime 16-bit address:

#include <web64.h>
#include <assets/generated.h>

void main(void) {
    VoidCall(title_play_address);
}

A constant address lowers to one absolute JSR. The address must refer to an initialized routine whose calling convention takes no parameters.

VoidCall is a function-like macro, so every .c translation unit that uses it must include <web64.h> itself; an include in another .c file is not project-global. A missing include produces c-implicit-function-declaration on the call line and blocks the build instead of emitting an unresolved _VoidCall. Repeating the exact macro definition produces a non-blocking c-macro-redefinition-identical warning for backwards compatibility. A different replacement definition produces the blocking c-macro-redefinition error. Warnings remain visible but do not prevent Start; only error diagnostics make a build unrunnable.

C runtime header examples

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

uint8_t lives = 3;
bool running = true;

void main(void) {
    lives--;
}

stdio.h declares blocking getchar, puts, and putchar for the tiny runtime, plus restricted compiler-lowered printf for string-literal formats with %d values. getchar waits on C64 KERNAL GETIN, does not echo, and returns the raw unsigned input byte widened to int; live keyboard input therefore does not return EOF. It performs no ASCII, PETSCII, or screen-code conversion. #pragma charset instead rewrites source string literals at compile time before a call such as puts, so it has no effect on bytes received by getchar. Input and output use their configured stdin and stdout backends, and each runtime module is linked only when a surviving call needs it. File I/O declarations and fprintf/sprintf are intentionally absent until they have executable implementations.

Screen and color RAM example

#include <stdint.h>
#include <c64.h>

void main(void) {
    *(volatile uint8_t *)VIC_BORDER = VIC_COLOR_BLUE;
    *(volatile uint8_t *)VIC_BACKGROUND = VIC_COLOR_BLACK;
    *(volatile uint8_t *)C64_SCREEN_RAM = 1;
    *(volatile uint8_t *)C64_COLOR_RAM = VIC_COLOR_WHITE;
}

The typed register aliases from c64.h can express chip register writes more clearly:

#include <c64.h>

void main(void) {
    VIC->border_color = VIC_COLOR_BLUE;
    VIC->background_color0 = VIC_COLOR_BLACK;
}

Joystick and sprite helper example

#include <stdint.h>
#include <joy.h>
#include <sprite.h>

uint8_t joy;

void main(void) {
    sprite_enable(1);
    sprite_set_pos(0, 80, 100);
    sprite_set_color(0, VIC_COLOR_LIGHT_GRAY);

    joy = joy_read();
    if (!(joy & JOY_FIRE)) {
        BACKGROUND_COLOR = VIC_COLOR_RED;
    }
}

SID register example

#include <stdint.h>
#include <c64.h>

void main(void) {
    *(volatile uint8_t *)SID_VOICE1_FREQ_LO = 0x11;
    *(volatile uint8_t *)SID_VOICE1_FREQ_HI = 0x25;
    *(volatile uint8_t *)SID_VOICE1_ATTACK_DECAY = 0x09;
    *(volatile uint8_t *)SID_VOICE1_SUSTAIN_RELEASE = 0xf0;
    *(volatile uint8_t *)SID_VOLUME_FILTER_MODE = 0x0f;
    *(volatile uint8_t *)SID_VOICE1_CONTROL = 0x21;
}

0x21 is SID_WAVE_SAW | SID_GATE. Prefer the named constants in project code; immediate register values remain useful when matching a datasheet or an existing assembly routine exactly.

Web64 asset access from C

assets/generated.h is produced from the virtual project asset records at compile time. It is the supported C-facing contract for browser-local assets: C code can refer to deterministic labels, sizes, asset-kind constants, typed data aliases, read-only flags, and the implemented Asset Model v1 descriptor declarations/constants without hard-coding assembler names by hand.

Asset filenames normally retain their existing C-safe symbol stem. When linked assets intentionally share a stem, as with a CharPad import containing a charset, blockset, and map, Web64 assigns role-qualified public C prefixes such as _charset, _blockset, and _tilemap. The assembly payload labels remain _chars, _blocks, and _map, so existing generated .inc files and mixed C/assembly projects remain compatible while every alias, size macro, view, and descriptor in assets/generated.h stays unique.

The generated header makes asset labels visible to the C compiler and final assembler namespace. When generated C actually references an asset data label, a C-only build embeds that payload once on demand. A hybrid build reuses an existing assembly label or .incbin instead of emitting a duplicate. Descriptor- and size-only references do not embed payload bytes. Browser-local asset files remain the canonical project records; generated .inc and .sid outputs remain derived assets where the IDE pipeline creates them. SID Tracker generates one .sid binary and one .inc, not a duplicate .bin.

web64/assets.h and assets/generated.h expose the current Asset Model v1 descriptor shapes and generated descriptor constants for source-backed charsets/chars, sprite banks, blocksets, maps, and SID files. Descriptor member reads lower to project metadata constants, while a data-member or data-label reference selects the payload for embedding. These headers define the asset data contract; applying sprites or maps, decompression, overlays, and loader policy remain explicit project/runtime operations unless a documented helper provides them.

A Sprite Editor .spritepair.json record is descriptor-only. The C asset bridge uses the same shared schema validator as the editor, resolves the multicolor base and mono overlay banks, and emits a Web64SpriteOverlayAsset referencing both Web64SpriteAsset descriptors. It never embeds the JSON text. Missing or duplicate layer paths, wrong modes, zero/unequal frame counts, and more than 256 frames are build diagnostics. Referencing pair metadata alone links no runtime; using web64_sprite_render_asset_pair() selects only the direct sprite module, while <web64/sprite-mux.h> selects its independent PAL mux module.

Web64SpriteOverlayBinding records the installed frame-zero VIC pointers; the application remains responsible for copying and 64-byte-aligning both banks in the active VIC bank. Direct pair rendering validates both frame indices and pointer arithmetic atomically. PAL scheduling uses caller-owned 1–24-layer double buffers, 24-byte prepared display-list entries, and 16-bit scheduled raster positions, so line 300 cannot alias line 44. Commit prepares complete owned-slot VIC control snapshots and the IRQ consumes them through patched absolute-indexed low/high windows. Reuse admission reserves ceil((300 + 48 * layers + 63) / 63) PAL lines: seven for one layer and eight for an atomic pair. Alignment-swept fast intervals peak at 283/337 cycles; KERNAL entry plus the demonstrated acknowledgement wrapper yields 336/390-cycle end-to-end paths, still leaving the full 63-cycle safety line. The 49-cycle next-event dispatcher tail is faster than the bundled Copper64 76-cycle normal irqHandlersReturn + fetchNext reference segment. The preserving service keeps A/X/Y intact, while web64_sprite_mux_irq_service_fast() is available when an enclosing dispatcher already owns that register envelope. IRQ service follows the mux-owned armed boundary/event identity instead of treating the delayed current raster as the originating compare. The mux preserves unowned hardware slots, publishes only at the armed line-300 boundary, and leaves vector installation, interrupt acknowledgement/chaining, the game tick, and RTI to application code. The standalone sprite-multiplexer-overlay example verifies motion in every accepted logical entry over 120 consecutive complete PAL frames.

Supported C asset records are project-local records whose kind is one of asset, binary, blob, sprite, spritebank, spriteanimation, charset, char, tile, block, blockset, tilemap, map, sid, or source. Typical file extensions are .bin, .raw, .dat, .spr, .chr, .ch8, .blk, .blocks, .map, .w64map, and .sid. A .w64sid record is editable composition source, not a runtime C asset. Its generated .sid is selected for assets/generated.h; an older generated .bin remains a fallback only when the project has no generated .sid. Unsupported kinds produce a c-unsupported-asset-kind diagnostic instead of becoming silent zero addresses.

The built-in kind constants are provided by web64/assets.h and re-used by assets/generated.h:

#define WEB64_ASSET_MODEL_VERSION 0x0001
#define WEB64_GENERATED_ASSETS_VERSION 0x0001
#define WEB64_ASSET_ADDRESS_NONE 0x0000
#define WEB64_ASSET_REF_NONE 0x0000
#define WEB64_SPRITE_BLOCK_NONE 0xff
#define WEB64_ASSET_KIND_BINARY 1
#define WEB64_ASSET_KIND_CHAR 2
#define WEB64_ASSET_KIND_CHARSET 3
#define WEB64_ASSET_KIND_SPRITE_MONO 4
#define WEB64_ASSET_KIND_SPRITE_MC 5
#define WEB64_ASSET_KIND_SPRITE_OVERLAY 6
#define WEB64_ASSET_KIND_BLOCK 7
#define WEB64_ASSET_KIND_BLOCKSET 8
#define WEB64_ASSET_KIND_MAP 9
#define WEB64_ASSET_KIND_SID 10
#define WEB64_ASSET_KIND_SOURCE 11

Asset paths are converted into C-safe symbols from the file basename with the extension removed. Non-identifier characters become _, and names that do not start with a C identifier character are prefixed. For example, assets/sprites/player.spr becomes player, while assets/sprites/player ship.spr becomes player_ship. Duplicate basenames that normalize to the same C symbol produce c-duplicate-asset-symbol.

The physical data labels match the names generated by the IDE asset editors: <symbol>_chars for charsets, <symbol>_sprites for sprite banks, <symbol>_blocks for block sets, <symbol>_map for maps, and <symbol>_sid for SID files. Payload labels are flat mutable unsigned char[] declarations, so games can update material maps, collected-object cells, animation data, and other RAM-backed asset bytes directly while retaining compatibility with byte indexing, memcpy, assembly labels, and pointer arithmetic. Historical base names remain C aliases, so existing source using player continues to address player_sprites. End labels and typed Asset Model descriptors remain read-only metadata. The metadata contract retains the historical start/end names while also exposing the physical data/dataEnd labels to build tools.

Assets whose dimensions are known also receive mutable multidimensional views:

Each family also has a <data-label>_view alias, a <data-label>_rank constant, and dimension-count constants such as _row_count, _column_count, _frame_count, or _character_count. Map views use uint16_t cells when the map's index width is two bytes; all other listed views use unsigned char. The views contain no copied data and create no C64 storage: they are typed projections over the same original payload label.

#include <stdint.h>
#include <assets/generated.h>

uint8_t block = level_map_rows[player_y][player_x];
uint8_t character = terrain_blocks_grid[block][tile_y][tile_x];
uint8_t pixels = font_chars_glyphs[character][pixel_row];
uint8_t sprite_data = player_sprites_frames[walk_frame][sprite_byte];

Runtime indexes use Web64-C's multidimensional row-major addressing. Constant indexes fold to direct payload offsets. As with ordinary Web64-C arrays, generated views do not add runtime bounds checks. Use the emitted descriptor and dimension constants when indexes can originate outside trusted game data.

For a sprite asset named player.spr, the generated header includes:

#define WEB64_ASSET_KIND_SPRITE_MC 5
extern unsigned char player_sprites[];
#define player player_sprites
extern const unsigned char player_sprites_end[];
#define player_end player_sprites_end
#define player_size 128
#define player_sprites_size player_size
#define player_kind 5
#define player_data player_sprites
#define player_bytes player_sprites
#define player_readonly 0
#define player_mutable 1
#define player_sprites_frames ((unsigned char (*)[64])player_sprites)
#define player_sprites_view player_sprites_frames
#define player_sprites_rank 2
#define player_sprites_frame_count 2
#define player_sprites_byte_count 64

Use the editor data label or _data/_bytes aliases when a routine needs an asset pointer. Use _size in initializers, conditions, copy loops, and bounds checks. Use _kind when one C source handles multiple generated assets.

#include <stdint.h>
#include <assets/generated.h>

uint16_t player_size_bytes = player_size;
const unsigned char *player_ptr = player_data;

void main(void) {
    if (player_kind == WEB64_ASSET_KIND_SPRITE_MC) {
        asm_load_player_sprite();
    }
}

A binary/blob asset follows the same rules:

#include <stdint.h>
#include <assets/generated.h>

const unsigned char *blob_ptr = example_blob_data;
uint16_t blob_size = example_blob_size;

void main(void) {
    if (example_blob_size) {
        asm_use_blob();
    }
}

Generated payload arrays and their typed views are writable in C. The compiler accepts a function call directly in a flat or multidimensional subscript and evaluates each index call once. The array object itself is still not assignable, and generated end labels and descriptor objects remain read-only.

#include <assets/generated.h>

unsigned char *ok = example_blob_data;
uint16_t next_offset(void);
uint8_t next_row(void);
uint8_t next_column(void);

void main(void) {
    ok = example_blob_bytes;  /* supported */
    example_blob[next_offset()] = 1;  /* supported; next_offset runs once */
    level_map_rows[next_row()][next_column()] = 0;
    example_blob = ok;        /* diagnostic: an array object is not assignable */
}

For supported descriptor families, assets/generated.h also includes <web64/assets.h>, declares a typed <symbol>_asset descriptor, creates a <symbol>_descriptor alias, and emits constants derived from the source asset metadata. Descriptor member reads such as title_asset.load_address lower directly to constants and do not allocate a descriptor block or embed the payload by themselves. Referencing the descriptor's data member, a generated data label, or a _data/_bytes alias selects that payload for on-demand embedding when no project assembly label already supplies it.

#include <stdint.h>
#include <assets/generated.h>

uint16_t font_chars = font_char_count;
uint8_t font_multicolor = (font_mode == 2);

uint16_t player_frames = player_frame_count;
uint8_t player_payload = player_payload_bytes_per_frame;  /* 63 visible bytes */
uint8_t player_record = player_bytes_per_frame;           /* 64 stored bytes */

uint8_t terrain_cell_bytes = terrain_bytes_per_block;
uint16_t level_cells = level1_cell_count;
uint8_t level_index_width = level1_index_width;

void main(void) {
    if (player_frames && level_cells) {
        asm_prepare_assets();
    }
}

The generated descriptor declarations have these public shapes where implemented:

extern const Web64CharsetAsset font_asset;
#define font_descriptor font_asset
#define font_char_count 256
#define font_bytes_per_char 8
#define font_mode 2

extern const Web64SpriteAsset player_asset;
#define player_descriptor player_asset
#define player_frame_count 2
#define player_bytes_per_frame 64
#define player_payload_bytes_per_frame 63

extern const Web64BlockSetAsset terrain_asset;
#define terrain_descriptor terrain_asset
#define terrain_bytes_per_block 6

extern const Web64MapAsset level1_asset;
#define level1_descriptor level1_asset
#define level1_cell_count 240
#define level1_index_width 2

extern const Web64SidAsset title_asset;
extern const unsigned char title_sid[];
#define title_descriptor title_asset
#define title_file_size 2980
#define title_c64_data_offset 124
#define title_c64_data_size 2856
#define title_c64_data (title_sid + 124)
#define title_payload (title_sid + 124)
#define title_payload_size 2856
#define title_load_address 4096
#define title_init_address 4096
#define title_play_address 4160
#define title_song_count 1

web64/assets.h defines descriptor and instance structs such as Web64CharAsset, Web64CharsetAsset, Web64SpriteAsset, Web64SpriteOverlayAsset, Web64BlockAsset, Web64BlockSetAsset, Web64MapAsset, Web64SidAsset, Web64Sprite, Web64SpriteOverlay, and Web64MapView. Web64SidAsset describes the complete PSID file and its C64 payload offset/size, load/init/play addresses, song selection, speed flags, and SID flags. Descriptor references use explicit 16-bit Web64AssetAddress payload-label addresses and Web64AssetRef descriptor-label addresses rather than public generated-label pointer initializers. Zero is reserved as WEB64_ASSET_ADDRESS_NONE/WEB64_ASSET_REF_NONE. Published SDK records continue to use explicit uint8_t kind, mode, cell-type, flag, and boolean fields so their ABI remains source- and assembler-readable; user records may use the bit-field contract below. Public enum ABI remains deferred.

In a hybrid project, assembly may explicitly import the complete SID file under the generated <symbol>_sid label:

title_sid:
    .incbin "assets/music/title.sid"

The explicit import is optional for C-only projects because a C reference to title_payload selects title_sid for on-demand embedding. If the hybrid assembly already defines title_sid, the compiler reuses it.

#include <string.h>
#include <assets/generated.h>

void load_title_music(void) {
    memcpy((void*)title_asset.load_address,
           title_payload,
           title_asset.c64_data_size);
}

title_asset.file_size and title_sid describe the complete PSID file, including its 124-byte header. Copying that pair directly to load_address is incorrect. The generated title_payload pointer skips c64_data_offset, and c64_data_size copies only bytes intended for C64 memory.

After the SID payload has been loaded and initialized, its generated zero-parameter play address can be called directly from C:

(*(void (*)(void))title_play_address)();

Constant targets lower to one absolute JSR; runtime uint16_t targets use a self-modifying call-site operand. An undeclared target such as title_play_address without #include <assets/generated.h> produces c-undeclared-identifier during C lowering instead of becoming a late undefined assembly symbol. Indirect calls with parameters remain diagnosed because an unknown target cannot use Web64's callee-owned ordinary parameter slots.

The same rule applies to copy arguments. A fabricated name such as enemy_sprites_any_symbol_blahblah produces c-undeclared-identifier on the C source line. A rejected call emits no partial argument pushes, so an invalid copy cannot silently corrupt the 6502 hardware stack.

The generated SID .inc can be imported by the assembly side of the same hybrid project. All macros from assets/generated.h are compile-time C metadata and are not re-emitted as assembler definitions; the generated .inc remains the assembly-side definition source. This prevents duplicate symbols when a loaded project contains an older generated .inc, while C expressions still fold the current asset-manifest values. Saving the W64SID asset regenerates both derived files; legacy tracker-generated includes are recognized by their generated-file marker, while genuine manual include overrides remain preserved.

The C-facing <symbol>_size is the complete PSID file size, while the W64SID assembly include retains its established <symbol>_size payload-size meaning. Use the unambiguous <symbol>_file_size and <symbol>_c64_data_size names when code needs to distinguish the complete PSID from its C64 payload.

The kind constants are descriptor categories, not broad payload buckets: char, charset, mono sprite, multicolor sprite, sprite overlay, block, block set, map, SID, source, and binary. Web64MapCellType reserves WEB64_MAP_CELL_CHAR and defines current block maps as WEB64_MAP_CELL_BLOCK. Sprite descriptor mode describes payload encoding; mutable Web64Sprite.flags controls the VIC-II instance bit, and helpers must reject applying an instance mode that does not match the asset payload. Sprite multicolor descriptor fields are defaults/compatibility metadata for the global $d025/$d026 registers, not per-instance storage. Source-backed v1 block payloads are row-major char-index bytes only; color/attribute layers stay absent until an explicit binary layout or separate addresses are implemented.

Use memcpy to copy a referenced payload to its runtime C64 address. Graphics labels use the same names shown by their IDE-generated assembly includes:

#include <string.h>
#include <assets/generated.h>

void main(void) {
    memcpy((void*)0x2800, bumps_chars, bumps_size);
    memcpy((void*)0x3000, c_joy_sprites, c_joy_size);
    memcpy((void*)0x3100, bank_2_sprites, bank_2_size);
    memcpy((void*)0x3400, enemy_sprites, enemy_size);
    memcpy((void*)title_load_address,
           title_payload,
           title_asset.c64_data_size);
}

For explicit fixed placement, compression, loaders, or cycle-sensitive copies, assembly remains available and may define the same physical data label. The generated C projection detects that definition and does not append another copy of the asset.

Generated asset labels participate in the C build graph. The IDE build output view marks assets/generated.h as a read-only generated header and records asset-label dependencies from the header to the backing project asset. Descriptor-only access must not select asset helper runtime modules. Duplicate C-safe symbols, unsupported placement/address policies, stale generated metadata, and unsupported asset kinds are reported as diagnostics when detected.

Inline assembly example

#include <c64.h>

void wait_raster(void) {
    asm("wait:\n    lda $d012\n    cmp #$80\n    bne wait");
}

void irq_guard(void) {
    asm volatile(R"(
    sei
    lda #$00
    sta $d020
    cli
)");
}

Inline assembly is emitted directly into the generated assembly module. Supported forms include asm("..."), asm volatile("..."), __asm__("..."), adjacent C string fragments, and simple R"(...)" raw string literals. GCC-style operand constraints and named operand substitution are not part of the current Web64 C subset; use constants, labels, or normal C statements around the assembly block. Keep labels unique if the inline block can be emitted more than once.

Mixed C and assembly

Use C for game state, control flow, data structures, hardware setup, SDK/runtime calls, and asset-driven logic. Use assembly where exact addressing modes, cycle counts, interrupt entry/exit, custom loaders, established music players, or a deliberately custom register contract matter.

void main(void) {
    asm_init_irq();
}

A call to asm_init_irq() emits jsr asm_init_irq, so a project assembly file can define:

asm_init_irq:
    sei
    rts

Use this boundary for raster IRQs, music players, fast sprite movement, decompression, asset copies, and other routines that are better expressed directly in 6502 assembly.

Handwritten native assembly may also call any registered, externally visible Web64 runtime entry by its underscore-prefixed label. Selected assembly translation units participate in the same registry-driven exact-closure analysis as generated C, so the call below links only the sprite-multiplexer module and the dependencies declared for that entry:

example_irq_service:
    jsr _web64_sprite_mux_irq_service_fast
    rts

A declaration in a C header does not link code by itself. The selected assembly reference is the dependency evidence; comments are ignored, and a project assembly file that deliberately defines the same registered entry remains authoritative instead of receiving a duplicate runtime implementation. Entries with _web64_rt argument windows publish their named labels for assembly callers, while zero-argument and deliberately register-oriented entries can be called directly as shown above.

Declaring and passing parameters to assembly routines

Web64 C treats names beginning with asm_ as direct, unmangled assembly labels. The C call:

asm_copy_sprite();

emits:

    jsr asm_copy_sprite

Declare the routine in a project header so the C source has a stable name, then define the same unmangled label in an .asm file:

/* game.h */
void asm_copy_sprite(void);

; routines.asm
asm_copy_sprite:
    ; assembly body
    rts

Always provide a prototype when an assembly routine accepts arguments or returns a value. Under web64-static-v0, a prototyped ordinary asm_ call uses exact-width deterministic parameter labels: arguments are evaluated left-to-right, staged safely, and written immediately before JSR. Under web64-stack-v1, assembly callees receive the same software-stack frame layout as generated C and must follow the documented frame/cleanup contract; use _fastcall when a small register boundary is preferable. Byte arguments occupy one byte, word/pointer arguments occupy two little-endian bytes, and stack-ABI wide arguments occupy their declared width.

/* game.h */
#include <stdint.h>
void asm_set_sprite_color(uint8_t slot, uint8_t color);

#include "game.h"
void main(void) {
    asm_set_sprite_color(0, 1);
}

; routines.asm
VIC_SPRITE0_COLOR = $d027

asm_set_sprite_color:
    ldx __web64_fn_asm_set_sprite_color_param_slot_0
    lda __web64_fn_asm_set_sprite_color_param_color_1
    sta VIC_SPRITE0_COLOR,x
    rts

The slot naming contract is __web64_fn_<function>_param_<parameter>_<base36-index>. A 16-bit parameter's low byte is at the label and its high byte is at label+1. Ordinary slots are static function-owned storage, so calls are non-reentrant and not interrupt-safe. A byte return value is placed in A; a 16-bit integer or pointer return uses A for the low byte and X for the high byte.

For a smaller direct-register boundary, declare a supported _fastcall shape. One byte argument arrives in A, one word/pointer argument arrives in A/X, and two byte arguments arrive in A then X:

_fastcall void asm_set_sprite_color_fast(uint8_t slot, uint8_t color);

asm_set_sprite_color_fast:
    tay
    txa
    sta $d027,y
    rts

Unsupported _fastcall signatures produce diagnostics. Shared C globals remain appropriate for persistent command blocks, multi-field return state, IRQ-facing mailboxes, and data that must remain visible between calls; external C globals use underscore labels such as _sprite_state. Legacy undeclared zero-argument asm_ calls remain accepted for existing projects, but arguments and return values require a declaration so the compiler can apply the correct ABI.

Web64 C expression and ABI contract

The expression frontend tokenizes, types, and parses expressions before lowering. Supported expressions include integer, floating, character, and string literals; identifiers; groups; casts; direct and indirect declared calls; prefix/postfix increment and decrement; unary +, -, ~, and !; compile-time sizeof; binary arithmetic, shifts, comparisons, bitwise/logical operators; comma and conditional ?:; supported assignments; fixed-size multidimensional indexes; typed pointer dereference; and struct/union member access backed by Web64 aggregate metadata. Floating constants and constant arithmetic are stored as IEEE binary32/binary64. Nonconstant floating conversion, arithmetic, comparison, and truth testing remain explicit errors until the software floating runtime is implemented.

Bit-fields

Web64-C supports named and unnamed bit-fields with 8- or 16-bit integer base types, including uint8_t, int8_t, uint16_t, int16_t, and their supported C integer spellings. Struct layout remains packed and padding-free. Consecutive bit-fields with the same allocation-unit width share that unit from least-significant bit upward in declaration order. A change between 8- and 16-bit base widths begins a new unit, as does a field that does not fit. An unnamed zero-width field ends the current unit. Union bit-fields all begin at bit zero.

typedef struct {
    int8_t *pattern_array;
    uint8_t *timing_array;
    Enemy *enemy_struct;
    Actor *actor_ptr;
    uint16_t index : 10;
    uint16_t negate_x : 1;
    uint16_t negate_y : 1;
    uint16_t flag_3 : 1;
    uint16_t flag_4 : 1;
    uint16_t flag_5 : 1;
    uint16_t flag_6 : 1;
} Glenn;

In the Web64 ABI, the four pointers above occupy eight bytes and the final seven fields share one little-endian 16-bit unit, so sizeof(Glenn) is 10. index occupies bits 0-9 and the flags occupy bits 10-15. This layout is deliberate and assembler-visible; do not assume another C compiler chooses the same implementation-defined packing order.

Dot and arrow access, assignment, compound assignment, and prefix/postfix increment and decrement preserve the other bits in the allocation unit. Signed fields are sign-extended when read, and stored values are truncated to the declared width. Positional aggregate initializers initialize named bit-fields in declaration order and do not consume a value for unnamed fields. A bit-field is not an addressable object: unary & and sizeof on an individual bit-field diagnose. A bit-field write is an inline read-modify-write sequence and is not automatically interrupt-atomic.

Bit-field extraction and insertion are emitted inline and add no runtime dependency. Merely enabling compiler support adds no generated instructions, data, call overhead, or linked bytes to code that does not declare or access bit-fields. Ordinary aggregate members retain their existing direct byte/word loads and stores under both web64-static-v0 and web64-stack-v1.

Scalar 32-bit integer members retain all four bytes in constant global/local aggregate initializers and standalone direct or pointer-member assignments. Supported assignment values are integer constants, scalar integer variables, and matching-width calls (wide call boundaries require web64-stack-v1). Narrow signed values are extended from their captured value without rereading a volatile source; pointer destinations remain stable across a value call that changes the pointer. Other wide member expressions, explicit noninteger wide member initializers, and wide member assignment-as-an-expression produce blocking diagnostics instead of partial writes. This bounded store support does not add general wide aggregate-expression reads, aggregate copies, or runtime aggregate initializer lists; byte/word member behavior and both ABIs are unchanged.

Multidimensional arrays

Web64-C stores fixed-size arrays in standard C row-major order. Every dimension is an integer constant expression. Only the outermost dimension may be omitted, and only when an initializer supplies its size:

uint8_t map[25][40];
uint16_t frames[][2] = {
    {0x1000, 0x1100},
    {0x1200, 0x1300}
};
char labels[][8] = {"PLAYER", "ENEMY"};

Nested braces, brace elision, partial rows, and character-row strings are accepted. Unspecified elements are zero-filled and excess elements diagnose. Global arrays are emitted directly in row-major data. Local arrays use Web64-C's function-owned storage; an initializer is executed again whenever control reaches the declaration.

Each subscript removes one array dimension. In map[row][column], map[row] is a complete 40-byte row and the second subscript selects its byte. sizeof(map), sizeof(map[row]), and sizeof(map[row][column]) therefore produce 1000, 40, and 1 without evaluating index expressions. sizeof(uint16_t[2][3]) produces 12. size_t is the Web64 16-bit unsigned size type.

Arrays decay to pointers to their first element in value contexts, while sizeof and unary & preserve the complete array type. For a multidimensional array, the first element is a row:

uint8_t read_cell(uint8_t rows[][40], uint8_t y, uint8_t x) {
    return rows[y][x];
}

uint8_t (*row)[40] = map + 4;

Array parameters adjust to pointer-to-array parameters. The equivalent explicit declaration is uint8_t (*rows)[40]. Pointer addition and subtraction scale by the complete pointee size, so advancing the pointer above advances 40 bytes. Arrays of structs, runtime-indexed struct elements, and multidimensional array members are supported.

Generated addressing folds constant indexes into direct label+offset operands. Runtime indexes use 16-bit row-major offsets; stride 1 removes scaling, power-of-two strides use shifts, and other constant strides use inline shift/add sequences. Function calls are valid index expressions for reads and writes, including generated asset views, and are evaluated once per subscript while the partial address is preserved. Runtime bounds checks are not inserted. Variable-length arrays and designated initializers are not supported and produce diagnostics. Individual objects must fit the 16-bit Web64 object-size model.

The integer model uses 8-bit _Bool, uint8_t, int8_t, char, and unsigned char; 16-bit uint16_t, int16_t, short, int, unsigned int, size_t, ptrdiff_t, and pointers; and 32-bit long, unsigned long, int32_t, and uint32_t. Plain char is signed. Integer promotions and usual arithmetic conversions use this rank/width model; signed byte identifiers, array elements, aggregate members, and function results are sign-extended before 16-bit arithmetic. Constant 16-bit multiply by 0, 1, -1, or a power of two lowers inline. Unsigned divide/remainder by a power of two use a logical shift or mask; signed divide uses a bias plus arithmetic shift to retain truncation toward zero, and signed remainder retains the dividend's sign. Other multiply/divide/remainder expressions keep the dependency-selected verified helpers. Thirty-two-bit add, subtract, bitwise operations, comparisons, shifts, multiply, divide, and remainder are lowered directly or through dependency-selected long helpers. The compatibility ABI rejects wide call boundaries; the stack ABI accepts wide objects and returns them through a hidden caller-provided pointer.

Function calls are clobber boundaries. Both ABIs evaluate arguments in declaration order. web64-static-v0 retains byte-exact temporary staging into deterministic function-owned parameter labels, including the established six-byte mixed-width (uint16_t, uint8_t, uint16_t, uint8_t) layout. web64-stack-v1 pushes contiguous argument bytes onto a downward software stack and lets the caller reclaim them after return. Its stack pointer is the zero-page pair $02/$03, and its frame pointer is $04/$05. Frames whose maximum local/parameter offset is below 256 use compact LDY #offset plus (frame),Y; larger valid frames use the wide address fallback and produce a performance warning. Caller cleanup can be combined with surrounding stack adjustments without changing callee code.

For variadic functions, argument zero occupies the lowest argument address and later arguments follow at increasing addresses. Default promotions are applied before materialization. va_start points immediately after the final fixed parameter, va_arg reads the requested promoted width and advances the pointer, and va_end has no runtime work. Fixed stack parameters and variadic slots therefore use the same declaration-order layout. The stack region and $02-$18 compiler-owned zero-page range are validated against project declarations and assembled memory ranges.

_fastcall remains available for zero arguments, one word/pointer argument in A/X, or two byte arguments in A then X. Ordinary byte returns use A and word/pointer returns use A/X. Stack-ABI values wider than two bytes use a hidden return pointer. Byte-returning compatibility helpers such as rand, putchar, and puts clear X for older callers. printf supports literal formats with %d arguments; unsupported specifiers and mismatched counts diagnose.

Function results may be a single-level pointer T *, const T * or T const *, where T is a supported scalar, void or a known aggregate typedef. Definitions and prototypes retain the pointee type and const qualification; the pointer itself remains a 16-bit A/X result and may be advanced. Writes through a const result and implicit conversion to a mutable pointer diagnose. Cast a void * result to a concrete pointer type before dereferencing it. Pointer-level qualifiers, volatile/restrict pointees and multiple pointer levels in return declarations remain unsupported and produce located errors. For a returned aggregate pointer, first store it in a named typed local and use local->field; computed call()->field access is not currently supported.

In the size profile, eligible compiler-owned stack-frame accesses may omit unnecessary Y and N/Z flag preservation when control-flow analysis proves those values unused. Both branch paths and loops are checked; unknown calls, opaque assembly and unsupported accesses retain conservative sequences. Each memory access remains in place once, including volatile accesses. This optimization adds no helper calls, RAM or ABI changes and leaves debug, balanced, speed and frame profiles unchanged.

The hidden return pointer is present even for a function with no C parameters. Wide results are delivered to the typed destination before any integer narrowing; assigning a 32-bit return to a byte or word keeps the low 8 or 16 bits, rather than interpreting A/X as a wide return. Direct and indirect calls, local destinations, indexed arrays, nested returns, and discarded wide calls preserve the same caller-cleanup contract. Floating-point storage returns preserve all four or eight representation bytes; this does not add nonconstant floating-point arithmetic or conversions.

Registered runtime argument windows (_web64_rt)

Web64 v2 adds _web64_rt for a bounded set of externally implemented SDK runtime declarations. It is not a general user-function attribute: C definitions, static declarations, variadic declarations, unregistered names, registry-signature mismatches, and combinations with _fastcall are errors. Ordinary user C and both existing C ABIs otherwise remain unchanged.

The native runtime registry owns the ordered argument names and exact byte widths. Every linked _web64_rt entry places one contiguous little-endian window immediately before the unchanged entry label and publishes these assembler symbols:

• _function__arg_window is the first byte of the window, and _function__arg_window_size is its exact byte count.
• _function__arg_<name> names an argument, while _function__argN is its positional alias.
• _function__arg_<name>__width and _function__arg_<name>__offset publish its exact width and offset.
• Existing __web64_fn_<function>_param_<name>_<index> labels alias the same bytes, preserving handwritten callers that already used the documented generated parameter labels.

For example, web64_actor_batch_cull_fast(view, viewport, visible, status) publishes an eight-byte window at _web64_actor_batch_cull_fast__arg_window; its four named pointer arguments occupy offsets 0, 2, 4, and 6, and _web64_actor_batch_cull_fast follows at window address + 8. Handwritten assembly may populate the named labels and JSR _web64_actor_batch_cull_fast without reconstructing an offset convention.

Web64-C evaluates arguments from left to right. When every expression is proven safe for direct placement, it writes each exact byte directly to the named window and calls the runtime entry. If an argument has a C-visible side effect or otherwise cannot be safely placed while the window is incomplete, the compiler retains the ordinary stable materialization path and only publishes the window after every expression has been evaluated. The called kernel sees the same absolute parameter bytes either way.

Argument windows are caller-writable and callee-read-only for the duration of a call. They are mainline, per-function, and non-reentrant: populate the complete window before JSR, and do not call the same entry from an interrupt or nested argument evaluation until the first call has consumed it. A/X/Y/flags and each registry record's published scratch remain caller-save. The runtime still does not allocate game state, copy assets, apply palettes, begin/commit mux frames, or own interrupts.

The initial v2 registry pilot covers actor-batch phase and adapter entries, web64_sprite_mux_submit(), and the four web64_world_shift_*() primitives. Only the called entry's window participates in exact closure; uncalled windows add zero bytes. Both web64-static-v0 and web64-stack-v1 use the same external runtime-window contract. Direct-label performance measurements start at the runtime entry and exclude C argument marshalling; _web64_rt overhead is measured separately.

Function-pointer casts, named function-pointer objects, function-pointer typedefs, and callback parameters retain return/parameter signatures. Constant targets lower to direct absolute JSR; runtime targets patch a call-site operand immediately before JSR $ffff. Under web64-stack-v1, indirect calls materialize typed arguments and hidden wide-return pointers exactly like direct calls. The compatibility ABI keeps its established zero-argument indirect-call restriction. Unresolved identifiers and mismatched argument counts are blocking diagnostics.

Under web64-stack-v1, automatic locals and parameters use recursive frames and direct/mutual recursion is allowed within the configured stack bound. Static locals retain static duration outside those frames. Under web64-static-v0, locals and parameters remain function-owned static storage and recursive call cycles diagnose. The compatibility ABI reserves $02-$09; the stack ABI reserves $02-$18 for stack/frame pointers and pseudo-registers. Both reserve $fb-$fe for argument/pointer scratch. Conflicting __web64_zeropage(address) declarations are rejected and all ownership is exposed by the memory-layout report.

Across translation units, external functions and objects retain underscore-prefixed public labels. static definitions receive deterministic module-private labels. Multiple external definitions and conflicting assembler-visible macro definitions are errors. A configured entry must have external linkage; static main is rejected. A helper-only C build with no external entry remains a warning for compatibility with mixed projects that provide their own assembly startup.

Inline assembly is supported through string forms such as asm("..."), asm volatile("..."), and __asm__("..."). Inline assembly labels share the generated assembler symbol namespace; local labels beginning with @ are scoped by the compiler, duplicate labels diagnose, and collisions with generated C/runtime labels diagnose. Inline assembly is a clobber boundary; preserve values explicitly when crossing it.

#pragma charset performs compile-time string encoding. Supported #pragma warn, #pragma cc64, and #pragma optimize forms produce stable compatibility or optimization-control diagnostics. Segment/linker-effect pragmas such as bss-name, data-name, rodata-name, and code-name are unsupported diagnostics because Web64 does not run a native linker script.

Optimizer safety contract

Web64-C normalizes persisted and IDE settings into the versioned debug, balanced, size, speed, and frame profiles. debug disables optimization; the other profiles enable their documented pass gates and enforce build/function growth plus optional worst-case-cycle budgets. speed minimizes aggregate executed cycles, while frame requires bounded worst-case critical-path evidence and reports unknown when loops, indirect calls, or other path costs cannot be proven. Every pass reports its gate, proof, cost decision, and whether it transformed output or only analyzed it.

The optimizer uses authoritative logical 6502 records with calibrated byte and best/worst cycle costs. Typed IR models functions, blocks, values, canonical array/pointer shapes, ranges, calls, ordered volatile/hardware effects, unknown pointer aliases, and opaque assembly fences. The IR currently crosses a verified legacy-emitter bridge: scalar/CFG transforms and downstream analyses are retained in reports, while only individually verified typed-lowering/emitter and local backend rewrites mutate generated code. The report therefore keeps outputMutation: false until the typed selector passes the same both-ABI checkpoint.

Implemented emitted-code optimizations include local duplicate load/store/compare cleanup, safe temporary reload removal, jump/dead-record cleanup, ABI-owned zero-page addressing, profitable typed 16-bit constant arithmetic, fixed-point specializations, and constant builtin materialization. Literal strlen, constant signed abs, and constant ASCII ctype predicates/conversions can disappear before runtime composition. Exact public/private/data runtime closure is then rooted only in surviving lowered imports; raw-source scans and the former fixed-point preparse are not dependency authorities. Hardware-register and C volatile accesses remain ordered, opaque inline assembly is a fence, and analysis-only call/frame, placement, loop, and frame candidates are never reported as emitted transformations.

Compiler compatibility appendix

Verified public examples

The governed web64-examples repository is the public example suite for Web64 C v1. c-compiler-conformance/c-compiler-conformance.web64proj prints PASS/FAIL for arithmetic, shifts, bitwise expressions, casts, nested calls, _fastcall runtime calls, and printf argument handling. tutorials/README.md links runnable projects for SDK headers, generated assets/generated.h, C64 register aliases, joystick helpers, sprite helpers, mixed C/ASM symbol behavior, runtime dependency boundaries, and unsupported-syntax diagnostics.

Web64 Game Runtime quick reference

The Game Runtime is composition-first. It never owns main(), never installs a hidden frame tick, and never links unrelated subsystems merely because a neighboring header was included. Call only the primitives your game needs, in the order your game loop owns.

Typical explicit game-loop order:

1. Read input and set intent/facing state.
2. Apply motion primitives, or step authored trajectories and explicitly project their Q12.4 result into the game-owned Motion/Actor position storage.
3. Run collision probes or sweeps, then apply game-owned responses.
4. Tick animation players using the caller-owned frame tick.
5. Render direct sprite states, or build and commit the next mux schedule.
6. At the application-owned raster IRQ, acknowledge the source and call preserving web64_sprite_mux_irq_service(), or call web64_sprite_mux_irq_service_fast() when the enclosing dispatcher already preserved A/X/Y, before chaining or executing RTI.

Game Runtime flag groups:

Hardware Loader Runtime

For synchronous raw/packed loading, the C and ASM ABI, transactional workspace, IRQ/music coexistence, SAVE/reinitialization and native disk authoring, see Web64 Hardware Loader Runtime. Its caller-owned memory and exact-link contracts apply to arbitrary applications, not only games.

Native Cartridge Runtime

For managed logical ROM resources and the expert physical bank/window API across Standard 8K, Standard 16K, Magic Desk and EasyFlash, see Web64 Native Cartridge Runtime. It documents C and web64/cartridge.inc assembly calls, generated resource handles, declared RAM ownership, status codes, and interrupt constraints.

Bitmap Drawing Runtime

The <web64/bitmap.h> runtime targets VIC-II standard bitmap memory: logical 320×200 hires pixels use indices 0–1 and logical 160×200 multicolor pixels use indices 0–3. Web64Bitmap is caller-owned and records the bitmap base, screen base, mode, background, VIC bank, D018 setup, and configured flag. web64_bitmap_configure() validates the VIC-visible layout without touching memory; web64_bitmap_init() additionally clears the bitmap, applies the caller palette, and activates the mode. Palette calls are explicit. Drawing calls never infer or rewrite palette assignments.

Imported PNG bitmaps in C

Import Bitmap... produces an editable charset and a character-index map. The charset contains reusable eight-byte bitmap cells; the map determines their position in the image. The import also creates a video-matrix plane and, for multicolor images, a Color RAM plane. Copying only <name>_charset to bitmap RAM copies the unique patterns once and cannot reproduce the displayed map.

After importing a 320×200 hires PNG named backdrop, save the project and use this C path. Include assets/generated.h and inspect its actual generated symbol names if the asset name differs. This example uses VIC bank 0, bitmap RAM at $2000, and screen RAM at $0400; keep the program and other assets clear of those addresses.

#include <stdint.h>
#include <web64/bitmap.h>
#include <assets/generated.h>

#define BITMAP_RAM ((uint8_t *)0x2000)
#define SCREEN_RAM ((uint8_t *)0x0400)

Web64Bitmap picture;

void main(void) {
    if (web64_bitmap_configure(&picture, BITMAP_RAM, SCREEN_RAM,
                               WEB64_BITMAP_MODE_HIRES) != WEB64_BITMAP_OK) return;
    if (web64_bitmap_load_map(&picture, &backdrop_tilemap_asset,
                              &backdrop_charset_asset) != WEB64_BITMAP_OK) return;
    picture.background = backdrop_charset_background_color;
    if (web64_bitmap_activate(&picture) != WEB64_BITMAP_OK) return;
    while (1) {}
}

web64_bitmap_load_map expands the map's one- or two-byte cell indexes into bitmap RAM and copies the imported video-matrix plane to screen RAM. For a multicolor PNG, select WEB64_BITMAP_MODE_MULTICOLOR; the same helper also copies its Color RAM plane to $d800. The generated charset background-color constant supplies the import's shared background. The helper accepts a complete 40×25 bitmap-character map. Use the Map Editor's linked charset mode and assets/generated.h to confirm the mode and symbol names.

Assembly callers can include web64/bitmap.inc and use web64_rt_prepare_bitmap_load_map bitmap, map, charset to fill the six-byte _web64_rt argument window, or web64_rt_call_bitmap_load_map bitmap, map, charset to prepare it and call the routine. The editor's right sidebar shows these macro arguments as you type.

Checked plot, get, horizontal/vertical line, general line, rectangle, filled rectangle, and ellipse calls validate context, logical coordinates, pixel index, and operation. Their _fast counterparts require those preconditions. Replace and XOR are available for ordinary drawing. Dot and circle are transparent aliases for plot and equal-radius ellipse. The optimized general-line path canonicalizes endpoint order, selects a mode/operation/major-axis/minor-direction kernel, and advances the physical bitmap cursor incrementally. The independent benchmark covers both ABIs, both modes, shallow and steep octants, reverse endpoints, and horizontal lines; the maximum 319×199 hires diagonal measures 19,218 cycles under web64-static-v0 and 19,219 under web64-stack-v1, inside the 19,267-cycle acceptance gate.

web64_bitmap_flood_fill() and _fast() are intentionally replace-only in v1. Connectivity is four-neighbor against the logical source index read at the seed. The caller supplies a bounded Web64BitmapFloodWorkspace; there is no recursion and no hidden allocation. The checked entry validates the complete surface, seed, replacement, workspace descriptor, span extent, address wrap, and overlap with the context, bitmap, screen RAM, workspace descriptor, and Color RAM before mutation where possible. Each span is recorded before it is painted. Aligned span discovery and replacement compare and write complete bitmap bytes using the hires $00/$ff or multicolor $00/$55/$aa/$ff repeated-index patterns; adjacent byte columns advance by eight physical bitmap bytes, while irregular boundaries retain masked logical-pixel handling. If capacity is exhausted, every recorded span is restored through the same byte-oriented path to the original source index, workspace.used remains at the deterministic exhausted count, and status WEB64_BITMAP_WORKSPACE_EXHAUSTED is returned. Flood fill modifies bitmap bytes only and never changes screen RAM or Color RAM; the replacement index must already be valid for every affected cell palette.

WEB64_BITMAP_FLOOD_STORAGE(name, capacity) declares caller-owned span storage plus its descriptor, and WEB64_BITMAP_FLOOD_WORKSPACE_INIT(name, capacity) initializes the descriptor at run time. The flood benchmark is deliberately separate from line timing and covers small, fragmented, corridor, large-open, and near-full-screen regions for checked and fast calls in both bitmap modes, with an independent four-neighbor oracle and screen/Color RAM invariants.

Trajectory Pattern Runtime

A Web64TrajectoryPattern stores shared immutable 3-byte segments: signed pixel delta_x, signed pixel delta_y, and a 1–255-frame duration. Each caller-owned 19-byte Web64TrajectoryState carries independent Q12.4 position, traversal index/direction, prepared quotient/remainder, and centered error state. Forward, reverse, loop, ping-pong, X/Y mirroring, exact transition events, one-frame segments, and maximum-duration segments use the same public representation. Every segment reaches its exact mathematical endpoint; repeated loops cannot accumulate interpolation drift.

The optional first-class .w64traj authoring asset and independent Canvas Trajectory Editor compile to the same raw triplets; they do not change this runtime. The generated .traj contains no anchor, map, appearance, editor, or world metadata, and can be used from arbitrary caller coordinates by C, assembly, or custom code. The authoring source is never a runtime dependency. See Trajectory assets and Trajectory Editor for the generated-family and Tiled interchange workflow.

The selected 6502 strategy is measured generated-table hybrid preparation plus centered DDA. Duration one is direct, powers of two use shifts, duration three uses a complete generated quotient/remainder table (258 bytes), durations 5, 6, and 7 use compact fractional tables (10, 12, and 14 bytes), and duration 31 uses 5 integer bytes plus 62 fractional bytes. Other bounded durations retain exact arithmetic fallbacks. The fixed shared table set is therefore 361 bytes and the public state remains 19 bytes. On the representative 1,846-frame strategy gate the production hybrid measures 185,085 cycles, versus 202,494 for the zero-table hybrid, 207,028 for ordinary fixed preparation, and 245,959 plus 512 table bytes for reciprocal assistance. The tables are deterministically generated and exact-link only with scalar execution or the batch private-divider dependency; including declarations or allocating public trajectory storage links no table or runtime bytes.

web64_trajectory_step_batch() and web64_trajectory_step_batch_fast() advance up to 255 contiguous states in stable input order and write one event byte per state. The checked entry preflights the complete non-null, non-wrapping, non-overlapping state and event spans plus every state before mutation. The fast entry requires already validated lockstep states that share one immutable pattern, segment index, phase, and traversal mode; per-state X/Y negation may differ. Its RAM-resident self-modifying kernel is mainline-only and non-reentrant. It retains only patched operand addresses, detects caller-buffer relocation, and reconstructs every semantic decision from the public 19-byte states, so C or assembly may inspect or mutate those states between calls.

The strengthened eight-actor performance gate measures one direct-label batch call, excluding C argument marshalling and host-side pointer relocation while including JSR/RTS, transition preparation, public writes, and any required cold operand repatch. Its complete 24-variant matrix covers both C ABIs, four code origins, stable caller buffers, and both adverse $fb/$fc state/event low-byte arrangements. The current worst stable call is 3,481 cycles and the worst cold relocation/repatch call is 3,786 cycles. Both are below the 3,931-cycle practical acceptance gate (20% of a 19,656-cycle PAL frame); the cold case retains 145 cycles of headroom. The 4,914-cycle 25% line remains the absolute rejection ceiling, not the acceptance target.

Interoperability is explicit and additive. WEB64_TRAJECTORY_APPLY_BODY() projects a state into an existing Web64Motion2D; WEB64_TRAJECTORY_APPLY_POSITION() projects into caller-owned Actor Batch X/Y arrays. Both are transparent header-only assignments: they allocate nothing, hide no mirror, and link no adapter. Both ABI builds are byte-identical to spelling the same four public-buffer assignments by hand, so the convenience boundary adds no instructions, bytes, or calls. The scalar executor depends on no Actor, Motion, Sprite, or Mux module. Batch execution exact-links only game-trajectory.asm and game-trajectory-batch.asm; no Actor, Sprite, or Mux runtime is pulled in. A verified mixed pipeline steps trajectory state, publishes it into Actor SoA storage, culls, builds public sprite commands, and submits them to the mux with exactly five unique closures and neither redundant actor-motion nor direct-sprite code. Games may instead consume the same state from assembly or render it through the direct sprite runtime, as the standalone example does.

Every parameterized trajectory entry follows _web64_rt. web64/trajectory.inc owns the packed layout offsets, limits, masks, event bits, status constants, and standard web64_rt_prepare_trajectory_* / web64_rt_call_trajectory_* helpers; compatible web64_trajectory_prepare_* / web64_trajectory_call_* aliases remain. web64/runtime.inc is the optional whole-registry catalog for callable labels and exact-width named argument windows. The trajectory helpers expand to ordinary assembly, add no hidden storage or adapter, and unused helpers link no runtime. The independent Kick-compatible scalar oracle uses the same pointer-based public state contract. Across an origin/alignment sweep it measures 716,485 cycles. Web64 measures at most 676,801 cycles under web64-static-v0 and 676,782 under web64-stack-v1, including legitimate direct-label preparation and calls but excluding C argument marshalling: 39,684 cycles (5.539%) and 39,703 cycles (5.541%) of headroom. The trajectory-patterns example runs eight independently phased instances sharing one pattern, exercises every X/Y negation combination plus loop/ping-pong behavior, exposes the state to an assembly reader, and exact-links only game-trajectory.asm plus the deliberately selected direct sprite renderer. Its trajectory-patterns-asm companion uses a setup-only fast batch window in the native hot loop and proves the helpers preserve the existing sub-20% PAL measurements.

Native overlay pairs and PAL sprite multiplexing

A .spritepair.json file is an editor/compiler descriptor, not a runtime byte payload. The compiler applies the Sprite Editor shared validator, resolves one multicolor base bank and one mono overlay bank, and emits a Web64SpriteOverlayAsset that references both Web64SpriteAsset descriptors. Missing layers, duplicate paths, wrong modes, zero or unequal frame counts, and counts above 256 are compile diagnostics. Merely compiling pair metadata links no runtime and embeds no JSON bytes.

Web64SpriteOverlayBinding adds only the installed frame-zero VIC pointer values. The application must copy both 64-byte-aligned layer banks into the active VIC bank. web64_sprite_render_asset_pair() validates both independent frame indices and pointer additions before touching VIC state, applies descriptor colors, shares position/expansion/priority, forces the base to multicolor and overlay to mono, and places the overlay in the higher-precedence VIC slot. web64_sprite_apply_overlay_palette() is the explicit $d025/$d026 write.

The PAL mux is caller-owned and double buffered. Capacity is 1–24 physical layers; a pair consumes two and is always accepted or dropped atomically. begin_frame() opens the inactive buffer, submissions are ordered by descending priority then submission order, and commit() publishes one pending schedule. event_line, end_line, and per-slot interval ends are 16-bit raster positions, so line 300 cannot alias line 44. Commit converts accepted entries into 24-byte prepared display-list records, including complete owned-slot VIC control snapshots. Stable-topology adapters may publish a deterministic layout generation and refresh that schedule without rebuilding it. stable_identity_x_low is a public proof byte: the fused adapter sets it only after proving the viewport's entire representable VIC X range is below 256; stable commit may then omit the cumulative X-high scan. A generic or high-X schedule leaves it clear and uses the complete scan. The raster IRQ uses patched absolute-indexed low/high windows and direct stores rather than recomputing masks. Schedules with at most ten accepted entries patch only the live low operand window; larger capacities retain the complete low/high patcher. Reuse admission reserves ceil((300 + 48 * layers + 63) / 63) PAL lines: seven for one layer and eight for an atomic pair. The measured worst aligned fast intervals are 283 and 337 cycles; modeled KERNAL entry plus the example acknowledgement wrapper brings the end-to-end paths to 336 and 390 cycles, below the 378/441-cycle budgets that remain after the full 63-cycle safety line. The 49-cycle Web64 handler-tail-to-next-compare path beats the bundled Copper64 normal irqHandlersReturn plus fetchNext reference path of 76 cycles for that equivalent dispatch segment. IRQ dispatch follows the mux-owned armed compare identity, so entry latency cannot confuse line 300 with a later current raster value. A pending schedule is consumed only by the armed PAL line-300 boundary; without another commit, the active schedule repeats. NTSC initialization returns WEB64_SPRITE_MUX_UNSUPPORTED_STANDARD.

The mux updates only its owned hardware slots and owned bits in $d010/$d015/$d017/$d01b/$d01c/$d01d, plus their coordinates, colors, and pointer entries. $d025/$d026 are the active mux shared palette. The application retains the IRQ vector, source identification and $d019/CIA acknowledgement, chaining, game tick, and RTI. web64_sprite_mux_irq_service() preserves A/X/Y; web64_sprite_mux_irq_service_fast() clobbers them and is for a wrapper such as the KERNAL $0314 dispatcher that already owns the register envelope. Both paths use module-local absolute scratch rather than compiler zero page $02-$17 or call scratch $fb-$fe.

See the standalone sprite-multiplexer-overlay project in web64-examples for nine moving native overlay pairs rendered as eighteen physical layers. A compact unsigned 32-sample sine lookup supplies smooth side-to-side X coordinates at quarter-turn phase offsets, so the rows weave without linking the Motion runtime. Three pairs simultaneously fill the six owned slots and six later pairs exercise repeated two-slot reuse. Every pair supplies independent four-frame base and overlay indices; the runtime converts both pointers, preserves shared geometry, forces a multicolor base and mono overlay, and assigns the overlay higher VIC precedence. The final low-priority pair is dropped as one logical entry and two physical layers. Its live PAL gate requires 120 consecutive complete frames with no cherry-picking, exact frame/tick progression, the bounded bidirectional lookup wave and all four base/overlay frames in every active pair, at least forty bright mono-overlay pixels in every pair region, stable reserved HUD bytes, and the same deterministic atomic drop.

Open actor-batch runtime

Web64ActorBatchView points at the existing caller-owned active IDs and Q12.4 position, velocity, geometry, category, and mask arrays. Animation, sprite bindings, visible records, coherent X order, actor pairs, resolved render commands, bounds, and status remain separate public buffers. Capacities and actor IDs are at most 255. Native overlay pairs carry independent base and overlay frames but remain one atomic render command. Checked calls validate before mutation; _fast calls accept documented prepared layouts and use the same buffers. Every phase is an exact-closure module, so selecting motion does not link culling, pair generation, commands, or either renderer.

The X-sweep repairs caller-owned order deterministically by left edge and actor ID, applies symmetric category/mask filtering and half-open AABBs, emits each overlapping pair once, and reports predictable buffer overflow. Culling preserves active-ID order and emits only positions representable by the explicit camera viewport. Command building resolves all frame and pointer arithmetic before append, so a bad layer cannot expose half a pair. The direct adapter sorts by priority and stable order, touches only its owned slots, and gives an overlay the higher VIC precedence. The mux adapter submits resolved commands but never begins or commits a frame. Neither adapter copies sprite bytes or writes the shared palette implicitly.

web64_actor_batch_run_mux_fast() is the production fused adapter for callers that can prove the pipeline facts in Web64ActorMuxPipeline.flags. Bounds, animation preparation, pair results, stable topology/order, and preintegrated motion can be supplied or retained openly by the application; no private runtime mirror replaces them. Its self-modifying kernels are RAM-resident, mainline-only, non-reentrant, and include operand preparation in their measured cost. The matching web64/actor-batch.inc publishes every structure offset, flag, status, entry label, and _web64_rt argument-window symbol for native or Kick-compatible assembly consumers.

The canonical 24-actor workload has 18 visible actors, four overlay pairs, motion, animation, culling, pair output, public commands, and mux output. The frozen competent KickAssembler baseline is 15,338 cycles. The complete Web64 fused direct-label path, including legitimate internal preparation and JSR/RTS but excluding C argument marshalling, measures 14,908 cycles under web64-static-v0 and 14,914 under web64-stack-v1: 430 and 424 cycles of headroom (2.80% and 2.76%) with byte-identical semantic output. The original 9,828-cycle figure remains an aspirational research target, not a release gate. The independent _web64_rt measurement reduces the six-call C-facing overhead from 756 to 252 cycles under both ABIs.

Open _web64_rt runtime ABI

All 163 parameterized native web64_* runtime functions use registry-generated exact-width named argument windows. This includes hardware loading, disk and file I/O, cartridge resources, fixed-point math, asset copying, bitmap drawing, motion, collision, animation, direct sprites, sprite multiplexing, actors, actor batches, trajectories, and World. Ordinary application C remains ordinary C: the bundled external declarations select the runtime convention, pure arguments are written directly into the window, and side-effectful expressions retain stable ordinary marshalling. The 10 parameterless native runtime entry points need no window and retain their direct labels.

Every native Web64 runtime family now has a self-contained assembly include such as web64/fixed.inc, web64/actor-batch.inc, or web64/world.inc. Registry-generated web64_rt_prepare_* helpers fill complete exact-width named windows, while web64_rt_call_* helpers prepare and call the unchanged underscore-prefixed entry; parameterless entries receive the call form only. C-owned structs and buffers pass directly by emitted labels such as _view, with no copy or private mirror. The expansion is byte-identical to handwritten window stores plus JSR, and an unused family include links zero runtime bytes. web64/runtime.inc remains the optional whole-registry metadata catalog. Windows are public, adjacent to their entries, mainline-only, and non-reentrant unless an entry documents otherwise. No ABI call allocates memory, copies an asset implicitly, installs an interrupt, or hides caller-owned state.

The standalone actor-batch-arena example keeps 32 actors in open SoA storage, moves all 32 through an application-owned sine/velocity adapter, renders an 18-actor hot cohort with four independently animated native overlay pairs, reserves direct HUD slots 0–1, and gives the mux slots 2–7. Its stable PAL frame accepts nine logical entries and 13 physical layers, deterministically drops nine entries/nine layers, and repeatedly reuses slots. The executable gate completed 120 consecutive live PAL frames with all 18 visible actors observed moving, zero busy-frame submissions, correct atomic pair precedence, stable HUD bytes, and a measured 12,487-cycle application frame workload.

Runtime kernel performance and compatibility

The September 2026 runtime optimization campaign changes internal kernels, not public layouts or calling conventions. C under both supported ABIs and direct assembly use the same entries, exact-width windows, generated prepare/call helpers, and caller-owned state. Mainline helpers remain non-reentrant; no new IRQ ownership or scratch allowance is implied.

These are executed 6502 kernel measurements, not whole-game frame rates. C argument marshalling is additional: 52 cycles for the hires plot, 12 for the animation tick, 24 for the AABB call, 40 for the material lookup, and 58 for the sprite call in these fixtures. Explicit immediate-load/absolute-store ASM window preparation costs 42, 12, 24, 36, and 54 cycles respectively. Neither call boundary is hidden in the runtime comparison.

Bitmap addressing no longer walks preceding character rows, and animation addressing no longer walks preceding four-byte records. The direct sprite path adds one independently exact-linked 8-byte mask table while reducing total isolated closure by 5 bytes; renderer initialization alone does not link that table. Slot 0 costs eight extra cycles, while the other slots improve. No large generic lookup table or per-instance storage was added.

Web64CollisionMap row addressing honors the full 16-bit height and row stride. A pre-existing truncation made row 256 alias row 0; rows above 255 now access their correct cells. Out-of-range coordinates still return the configured outside material. The fixed address kernel adds 16 code bytes and costs five extra cycles for the measured row-1 case, in exchange for correctness and bounded work on taller maps.

The unchanged Ascender hybrid C/ASM example shrinks from 12,428 to 12,307 PRG bytes. Its sampled headless update/render maximum falls from 18,615 to 17,933 cycles, excluding raster idle. A separate real VICE run presents all 180 sampled PAL frames without a missed page flip, compared with two missed presentations with the baseline runtime. Canonical per-presentation screen/sprite output and native charset bytes remain identical; this is a bounded regression test, not a guarantee for every possible play session. The Mirror Pulse example also retains canonical rendering while shrinking by 59 bytes in both ABI rendering fixtures. Its published URL-loading demo disk is maintained separately and need not match the latest build.

Web64 Game Runtime World module quick reference

World is an independently linked module family within Web64 Game Runtime, alongside Motion, Collision, Animation, Sprites, and Actors. It streams already-linked native Web64 asset planes into screen RAM and Color RAM, but it does not own main(), the frame tick, IRQ policy, camera policy, collision meaning, or game rules.

Game Runtime World-module template families:

• World Static Map
• World Horizontal Scroller
• World Subpixel Motion Scroller
• World Vertical Scroller
• World Bidirectional Scroller
• World Multicolor Platformer
• World + Motion and Sprites

The moving templates use transactional double buffering and never modify the displayed VIC screen. A complete next viewport is rendered into the hidden page; D018, D016, and D011 are staged and committed together at the frame boundary. Physical page ownership is released only after presentation, so a high-speed or subpixel caller cannot render into a page that is still visible. Horizontal movement uses 38-column geometry and vertical movement uses verified 25-row geometry. Default buffered templates fill Color RAM once with a stable region color and perform no in-loop Color RAM writes; the static renderer and explicitly scheduled public APIs retain exact per-cell color support. Stopping and reversal preserve the exact partial fine phase.

The Subpixel Motion template keeps its authoritative camera position in Motion Q12.4 and passes that position through web64_world_camera_sync_x(). Its PAL-safe profile visibly demonstrates 0.125-4.0 pixels/frame, progressive acceleration and braking, reversal through zero, and deterministic settling without feeding rounded renderer coordinates back into physics. The renderer consumes up to four integer scroll steps per game tick so its displayed position tracks the Motion target instead of lagging behind it.

The executable benchmark measures complete sustained edge-to-edge movement using stable region Color RAM in the transactional buffered templates. Worst frames are 14,499 cycles horizontal (62.041% below the frozen 38,196-cycle path), 17,708 vertical (51.305% below 36,365), 15,223 bidirectional (60.145% below 38,196), and 14,746 multicolor bidirectional (61.394% below 38,196). The composed 0.125-4.0-pixel Motion + World update peaks at 16,083 cycles. Displayed-screen writes and in-loop Color RAM writes are zero; idle frames also perform zero screen writes. The equivalent public per-cell horizontal boundary path uses 31,485 cycles versus 37,156 for the repository c64lib tile2 compatibility path, a 15.263% advantage while both write 880 screen and 880 Color RAM cells.

Reference and print links:

• web64/loader.h — printable listing
• web64/loader.inc — printable listing
• web64/assets.h — printable listing
• web64/assets.inc — printable listing
• web64/disk.h — printable listing
• web64/disk.inc — printable listing
• web64/fixed.h — printable listing
• web64/fixed.inc — printable listing
• web64/game.h — printable listing
• web64/motion.h — printable listing
• web64/motion.inc — printable listing
• web64/bitmap.h — printable listing
• web64/bitmap.inc — printable listing
• web64/trajectory.h — printable listing
• web64/trajectory.inc — printable listing
• web64/collision.h — printable listing
• web64/collision.inc — printable listing
• web64/animation.h — printable listing
• web64/animation.inc — printable listing
• web64/sprite-runtime.h — printable listing
• web64/sprite-runtime.inc — printable listing
• web64/sprite-mux.h — printable listing
• web64/sprite-mux.inc — printable listing
• web64/actor-batch.h — printable listing
• web64/actor-batch.inc — printable listing
• web64/runtime.inc — printable listing
• web64/actors.h — printable listing
• web64/actors.inc — printable listing
• web64/game-compose.h — printable listing
• web64/world.h — printable listing
• web64/world.inc — printable listing

Web64 SDK header index

For exact printable source, use the raw links below or open the Web64 SDK Header Printouts page.

Web64 SDK reference

6502.h

Inline assembly and direct-memory convenience macros for 6502-centric C code.

Included headers: <stdint.h>.

Macros:

Header listing:

#ifndef WEB64_6502_H
#define WEB64_6502_H
#include <stdint.h>
#define PEEK(address) (*(volatile uint8_t*)(address))
#define POKE(address, value) (*(volatile uint8_t*)(address) = (uint8_t)(value))
#define PEEKW(address) (*(volatile uint16_t*)(address))
#define POKEW(address, value) (*(volatile uint16_t*)(address) = (uint16_t)(value))
#define CLI() __asm__("cli")
#define SEI() __asm__("sei")
#endif

assets/generated.h

Project-generated asset declarations exported into C builds from the current asset manifest.

Included headers: <web64/assets.h>.

Header listing:

#ifndef WEB64_ASSETS_GENERATED_H
#define WEB64_ASSETS_GENERATED_H
#include <web64/assets.h>
#endif

c64.h

Typed C64 hardware register blocks, memory map constants, colors, and device pointer macros.

Typedefs:

Structs:

Macros:

Header listing:

#ifndef WEB64_C64_H
#define WEB64_C64_H

/* Common C64 memory map. */
#define C64_RAM_BASE 0x0000
#define C64_BASIC_START 0x0801
#define C64_SCREEN_RAM 0x0400
#define C64_COLOR_RAM 0xd800
#define C64_CHAR_ROM 0xd000
#define C64_SCREEN_WIDTH 40
#define C64_SCREEN_HEIGHT 25
#define C64_SCREEN_CELL_COUNT 1000
#define C64_IO_BASE 0xd000
#define C64_KERNAL_ROM 0xe000

typedef unsigned char c64_reg8_t;

typedef struct c64_cpu_port_registers {
    volatile c64_reg8_t data_direction;
    volatile c64_reg8_t data;
} c64_cpu_port_registers;

typedef struct c64_screen_ram {
    volatile c64_reg8_t cells[1000];
} c64_screen_ram;

typedef struct c64_color_ram {
    volatile c64_reg8_t cells[1000];
} c64_color_ram;

#define C64_CPU_PORT ((volatile c64_cpu_port_registers*)0x0000)
#define C64_SCREEN ((volatile c64_screen_ram*)C64_SCREEN_RAM)
#define C64_COLOR ((volatile c64_color_ram*)C64_COLOR_RAM)
#define C64_SCREEN_ROWS ((volatile unsigned char (*)[40])C64_SCREEN_RAM)
#define C64_COLOR_ROWS ((volatile unsigned char (*)[40])C64_COLOR_RAM)
#define C64_CHAR_ROM_GLYPHS ((const unsigned char (*)[8])C64_CHAR_ROM)

/* VIC-II registers. */
typedef struct c64_vicii_registers {
    volatile c64_reg8_t sprite0_x;
    volatile c64_reg8_t sprite0_y;
    volatile c64_reg8_t sprite1_x;
    volatile c64_reg8_t sprite1_y;
    volatile c64_reg8_t sprite2_x;
    volatile c64_reg8_t sprite2_y;
    volatile c64_reg8_t sprite3_x;
    volatile c64_reg8_t sprite3_y;
    volatile c64_reg8_t sprite4_x;
    volatile c64_reg8_t sprite4_y;
    volatile c64_reg8_t sprite5_x;
    volatile c64_reg8_t sprite5_y;
    volatile c64_reg8_t sprite6_x;
    volatile c64_reg8_t sprite6_y;
    volatile c64_reg8_t sprite7_x;
    volatile c64_reg8_t sprite7_y;
    volatile c64_reg8_t sprite_x_msb;
    volatile c64_reg8_t control1;
    volatile c64_reg8_t raster;
    volatile c64_reg8_t lightpen_x;
    volatile c64_reg8_t lightpen_y;
    volatile c64_reg8_t sprite_enable;
    volatile c64_reg8_t control2;
    volatile c64_reg8_t sprite_y_expand;
    volatile c64_reg8_t memory_setup;
    volatile c64_reg8_t interrupt_status;
    volatile c64_reg8_t interrupt_enable;
    volatile c64_reg8_t sprite_priority;
    volatile c64_reg8_t sprite_multicolor;
    volatile c64_reg8_t sprite_x_expand;
    volatile c64_reg8_t sprite_collision;
    volatile c64_reg8_t data_collision;
    volatile c64_reg8_t border_color;
    volatile c64_reg8_t background_color0;
    volatile c64_reg8_t background_color1;
    volatile c64_reg8_t background_color2;
    volatile c64_reg8_t background_color3;
    volatile c64_reg8_t sprite_multicolor0;
    volatile c64_reg8_t sprite_multicolor1;
    volatile c64_reg8_t sprite0_color;
    volatile c64_reg8_t sprite1_color;
    volatile c64_reg8_t sprite2_color;
    volatile c64_reg8_t sprite3_color;
    volatile c64_reg8_t sprite4_color;
    volatile c64_reg8_t sprite5_color;
    volatile c64_reg8_t sprite6_color;
    volatile c64_reg8_t sprite7_color;
} c64_vicii_registers;

#define VIC_BASE 0xd000
#define VIC_SPRITE0_X 0xd000
#define VIC_SPRITE0_Y 0xd001
#define VIC_SPRITE1_X 0xd002
#define VIC_SPRITE1_Y 0xd003
#define VIC_SPRITE2_X 0xd004
#define VIC_SPRITE2_Y 0xd005
#define VIC_SPRITE3_X 0xd006
#define VIC_SPRITE3_Y 0xd007
#define VIC_SPRITE4_X 0xd008
#define VIC_SPRITE4_Y 0xd009
#define VIC_SPRITE5_X 0xd00a
#define VIC_SPRITE5_Y 0xd00b
#define VIC_SPRITE6_X 0xd00c
#define VIC_SPRITE6_Y 0xd00d
#define VIC_SPRITE7_X 0xd00e
#define VIC_SPRITE7_Y 0xd00f
#define VIC_SPRITE_X_MSB 0xd010
#define VIC_CONTROL1 0xd011
#define VIC_RASTER 0xd012
#define VIC_LIGHTPEN_X 0xd013
#define VIC_LIGHTPEN_Y 0xd014
#define VIC_SPRITE_ENABLE 0xd015
#define VIC_CONTROL2 0xd016
#define VIC_SPRITE_Y_EXPAND 0xd017
#define VIC_MEMORY_SETUP 0xd018
#define VIC_INTERRUPT_STATUS 0xd019
#define VIC_INTERRUPT_ENABLE 0xd01a
#define VIC_SPRITE_PRIORITY 0xd01b
#define VIC_SPRITE_MULTICOLOR 0xd01c
#define VIC_SPRITE_X_EXPAND 0xd01d
#define VIC_SPRITE_COLLISION 0xd01e
#define VIC_DATA_COLLISION 0xd01f
#define VIC_BORDER 0xd020
#define VIC_BACKGROUND 0xd021
#define VIC_BACKGROUND0 0xd021
#define VIC_BACKGROUND1 0xd022
#define VIC_BACKGROUND2 0xd023
#define VIC_BACKGROUND3 0xd024
#define VIC_SPRITE_MULTICOLOR0 0xd025
#define VIC_SPRITE_MULTICOLOR1 0xd026
#define VIC_SPRITE0_COLOR 0xd027
#define VIC_SPRITE1_COLOR 0xd028
#define VIC_SPRITE2_COLOR 0xd029
#define VIC_SPRITE3_COLOR 0xd02a
#define VIC_SPRITE4_COLOR 0xd02b
#define VIC_SPRITE5_COLOR 0xd02c
#define VIC_SPRITE6_COLOR 0xd02d
#define VIC_SPRITE7_COLOR 0xd02e
#define VIC_COLOR_BLACK 0x00
#define VIC_COLOR_WHITE 0x01
#define VIC_COLOR_RED 0x02
#define VIC_COLOR_CYAN 0x03
#define VIC_COLOR_PURPLE 0x04
#define VIC_COLOR_GREEN 0x05
#define VIC_COLOR_BLUE 0x06
#define VIC_COLOR_YELLOW 0x07
#define VIC_COLOR_ORANGE 0x08
#define VIC_COLOR_BROWN 0x09
#define VIC_COLOR_LIGHT_RED 0x0a
#define VIC_COLOR_DARK_GRAY 0x0b
#define VIC_COLOR_GRAY 0x0c
#define VIC_COLOR_LIGHT_GREEN 0x0d
#define VIC_COLOR_LIGHT_BLUE 0x0e
#define VIC_COLOR_LIGHT_GRAY 0x0f
#define COLOR_BLACK VIC_COLOR_BLACK
#define COLOR_WHITE VIC_COLOR_WHITE
#define COLOR_RED VIC_COLOR_RED
#define COLOR_CYAN VIC_COLOR_CYAN
#define COLOR_PURPLE VIC_COLOR_PURPLE
#define COLOR_GREEN VIC_COLOR_GREEN
#define COLOR_BLUE VIC_COLOR_BLUE
#define COLOR_YELLOW VIC_COLOR_YELLOW
#define COLOR_ORANGE VIC_COLOR_ORANGE
#define COLOR_BROWN VIC_COLOR_BROWN
#define COLOR_LIGHTRED VIC_COLOR_LIGHT_RED
#define COLOR_GRAY1 VIC_COLOR_DARK_GRAY
#define COLOR_GRAY2 VIC_COLOR_GRAY
#define COLOR_LIGHTGREEN VIC_COLOR_LIGHT_GREEN
#define COLOR_LIGHTBLUE VIC_COLOR_LIGHT_BLUE
#define COLOR_GRAY3 VIC_COLOR_LIGHT_GRAY
#define VIC_SPRITE_POINTER_BASE 0x07f8
#define VICII ((volatile c64_vicii_registers*)VIC_BASE)
#define VIC VICII

/* SID registers. */
typedef struct c64_sid_voice_registers {
    volatile c64_reg8_t freq_lo;
    volatile c64_reg8_t freq_hi;
    volatile c64_reg8_t pulse_lo;
    volatile c64_reg8_t pulse_hi;
    volatile c64_reg8_t control;
    volatile c64_reg8_t attack_decay;
    volatile c64_reg8_t sustain_release;
} c64_sid_voice_registers;

typedef struct c64_sid_registers {
    volatile c64_reg8_t voice1_freq_lo;
    volatile c64_reg8_t voice1_freq_hi;
    volatile c64_reg8_t voice1_pulse_lo;
    volatile c64_reg8_t voice1_pulse_hi;
    volatile c64_reg8_t voice1_control;
    volatile c64_reg8_t voice1_attack_decay;
    volatile c64_reg8_t voice1_sustain_release;
    volatile c64_reg8_t voice2_freq_lo;
    volatile c64_reg8_t voice2_freq_hi;
    volatile c64_reg8_t voice2_pulse_lo;
    volatile c64_reg8_t voice2_pulse_hi;
    volatile c64_reg8_t voice2_control;
    volatile c64_reg8_t voice2_attack_decay;
    volatile c64_reg8_t voice2_sustain_release;
    volatile c64_reg8_t voice3_freq_lo;
    volatile c64_reg8_t voice3_freq_hi;
    volatile c64_reg8_t voice3_pulse_lo;
    volatile c64_reg8_t voice3_pulse_hi;
    volatile c64_reg8_t voice3_control;
    volatile c64_reg8_t voice3_attack_decay;
    volatile c64_reg8_t voice3_sustain_release;
    volatile c64_reg8_t filter_cutoff_lo;
    volatile c64_reg8_t filter_cutoff_hi;
    volatile c64_reg8_t filter_resonance;
    volatile c64_reg8_t volume_filter_mode;
    volatile c64_reg8_t pot_x;
    volatile c64_reg8_t pot_y;
    volatile c64_reg8_t osc3_random;
    volatile c64_reg8_t env3;
} c64_sid_registers;

#define SID_BASE 0xd400
#define SID_VOICE1_FREQ_LO 0xd400
#define SID_VOICE1_FREQ_HI 0xd401
#define SID_VOICE1_PULSE_LO 0xd402
#define SID_VOICE1_PULSE_HI 0xd403
#define SID_VOICE1_CONTROL 0xd404
#define SID_VOICE1_ATTACK_DECAY 0xd405
#define SID_VOICE1_SUSTAIN_RELEASE 0xd406
#define SID_VOICE2_FREQ_LO 0xd407
#define SID_VOICE2_FREQ_HI 0xd408
#define SID_VOICE2_PULSE_LO 0xd409
#define SID_VOICE2_PULSE_HI 0xd40a
#define SID_VOICE2_CONTROL 0xd40b
#define SID_VOICE2_ATTACK_DECAY 0xd40c
#define SID_VOICE2_SUSTAIN_RELEASE 0xd40d
#define SID_VOICE3_FREQ_LO 0xd40e
#define SID_VOICE3_FREQ_HI 0xd40f
#define SID_VOICE3_PULSE_LO 0xd410
#define SID_VOICE3_PULSE_HI 0xd411
#define SID_VOICE3_CONTROL 0xd412
#define SID_VOICE3_ATTACK_DECAY 0xd413
#define SID_VOICE3_SUSTAIN_RELEASE 0xd414
#define SID_FILTER_CUTOFF_LO 0xd415
#define SID_FILTER_CUTOFF_HI 0xd416
#define SID_FILTER_RESONANCE 0xd417
#define SID_VOLUME_FILTER_MODE 0xd418
#define SID_POT_X 0xd419
#define SID_POT_Y 0xd41a
#define SID_OSC3_RANDOM 0xd41b
#define SID_ENV3 0xd41c
#define SID_WAVE_TRIANGLE 0x10
#define SID_WAVE_SAW 0x20
#define SID_WAVE_PULSE 0x40
#define SID_WAVE_NOISE 0x80
#define SID_GATE 0x01
#define SID_SYNC 0x02
#define SID_RING_MOD 0x04
#define SID_TEST 0x08

/* CIA, keyboard, and joyport registers. */
typedef struct c64_cia_registers {
    volatile c64_reg8_t pra;
    volatile c64_reg8_t prb;
    volatile c64_reg8_t ddra;
    volatile c64_reg8_t ddrb;
    volatile c64_reg8_t timer_a_lo;
    volatile c64_reg8_t timer_a_hi;
    volatile c64_reg8_t timer_b_lo;
    volatile c64_reg8_t timer_b_hi;
    volatile c64_reg8_t tod_10ths;
    volatile c64_reg8_t tod_seconds;
    volatile c64_reg8_t tod_minutes;
    volatile c64_reg8_t tod_hours;
    volatile c64_reg8_t serial_data;
    volatile c64_reg8_t interrupt_control;
    volatile c64_reg8_t control_a;
    volatile c64_reg8_t control_b;
} c64_cia_registers;

#define SID ((volatile c64_sid_registers*)SID_BASE)

/* CIA, keyboard, and joyport registers. */
#define CIA1_BASE 0xdc00
#define CIA1_PRA 0xdc00
#define CIA1_PRB 0xdc01
#define CIA1_DDRA 0xdc02
#define CIA1_DDRB 0xdc03
#define CIA1_TIMER_A_LO 0xdc04
#define CIA1_TIMER_A_HI 0xdc05
#define CIA1_TIMER_B_LO 0xdc06
#define CIA1_TIMER_B_HI 0xdc07
#define CIA1_TOD_10THS 0xdc08
#define CIA1_TOD_SECONDS 0xdc09
#define CIA1_TOD_MINUTES 0xdc0a
#define CIA1_TOD_HOURS 0xdc0b
#define CIA1_SERIAL_DATA 0xdc0c
#define CIA1_INTERRUPT_CONTROL 0xdc0d
#define CIA1_CONTROL_A 0xdc0e
#define CIA1_CONTROL_B 0xdc0f
#define CIA2_BASE 0xdd00
#define CIA2_PRA 0xdd00
#define CIA2_PRB 0xdd01
#define CIA2_DDRA 0xdd02
#define CIA2_DDRB 0xdd03
#define CIA2_TIMER_A_LO 0xdd04
#define CIA2_TIMER_A_HI 0xdd05
#define CIA2_TIMER_B_LO 0xdd06
#define CIA2_TIMER_B_HI 0xdd07
#define CIA2_TOD_10THS 0xdd08
#define CIA2_TOD_SECONDS 0xdd09
#define CIA2_TOD_MINUTES 0xdd0a
#define CIA2_TOD_HOURS 0xdd0b
#define CIA2_SERIAL_DATA 0xdd0c
#define CIA2_INTERRUPT_CONTROL 0xdd0d
#define CIA2_CONTROL_A 0xdd0e
#define CIA2_CONTROL_B 0xdd0f
#define CIA1 ((volatile c64_cia_registers*)CIA1_BASE)
#define CIA2 ((volatile c64_cia_registers*)CIA2_BASE)
#define KEYBOARD_COLUMN_PORT 0xdc00
#define KEYBOARD_ROW_PORT 0xdc01
#define KEYBOARD_COLUMN_DDR 0xdc02
#define KEYBOARD_ROW_DDR 0xdc03
#define KEYBOARD_ACTIVE_MASK 0xff
#define JOYPORT_1 0xdc01
#define JOYPORT_2 0xdc00
/* Joystick masks are active-low: (sample & JOY_FIRE) == 0 means pressed. */
#define JOY_UP 0x01
#define JOY_DOWN 0x02
#define JOY_LEFT 0x04
#define JOY_RIGHT 0x08
#define JOY_FIRE 0x10
#define JOY_ACTIVE_LOW 0x00
#define JOY_RELEASED_MASK 0x1f
#define JOY2_UP() (!(CIA1->pra & JOY_UP))
#define JOY2_DOWN() (!(CIA1->pra & JOY_DOWN))
#define JOY2_LEFT() (!(CIA1->pra & JOY_LEFT))
#define JOY2_RIGHT() (!(CIA1->pra & JOY_RIGHT))
#define JOY2_FIRE() (!(CIA1->pra & JOY_FIRE))
#define JOY_UP_P(v) (!((v) & JOY_UP))
#define JOY_DOWN_P(v) (!((v) & JOY_DOWN))
#define JOY_LEFT_P(v) (!((v) & JOY_LEFT))
#define JOY_RIGHT_P(v) (!((v) & JOY_RIGHT))
#define JOY_FIRE_P(v) (!((v) & JOY_FIRE))

/* Convenience aliases. */
#define VIC_BORDER_COLOR VIC_BORDER
#define VIC_BACKGROUND_COLOR VIC_BACKGROUND
#define VIC_SPRITE_POINTERS VIC_SPRITE_POINTER_BASE
#define BORDER_COLOR VIC->border_color
#define BACKGROUND_COLOR VIC->background_color0
#define SPRITE_ENABLE VIC->sprite_enable
#define SPRITE_MULTICOLOR VIC->sprite_multicolor

/* Common KERNAL entry points. */
#define KERNAL_CHROUT 0xffd2
#define KERNAL_CHRIN 0xffcf
#define KERNAL_READST 0xffb7
#define KERNAL_OPEN 0xffc0
#define KERNAL_CLOSE 0xffc3
#define KERNAL_CHKIN 0xffc6
#define KERNAL_CHKOUT 0xffc9
#define KERNAL_CLRCHN 0xffcc
#define KERNAL_GETIN 0xffe4
#define KERNAL_SCNKEY 0xff9f
#define KERNAL_PLOT 0xfff0
#define KERNAL_SETLFS 0xffba
#define KERNAL_SETNAM 0xffbd
#define KERNAL_LOAD 0xffd5
#define KERNAL_SAVE 0xffd8

#endif

c64lib/64spec.h

Browser-native c64lib assertion and machine-readable test-result declarations.

Included headers: <stdint.h>.

Functions:

Structs:

Macros:

Header listing:

#ifndef WEB64_C64LIB_64SPEC_H
#define WEB64_C64LIB_64SPEC_H
#include <stdint.h>
#define C64LIB_64SPEC_STATUS_IDLE 0
#define C64LIB_64SPEC_STATUS_RUNNING 1
#define C64LIB_64SPEC_STATUS_PASSED 2
#define C64LIB_64SPEC_STATUS_FAILED 3
typedef struct {
    uint8_t magic[2];
    uint8_t status;
    uint16_t passed;
    uint16_t failed;
} C64lib64specResult;
void c64lib_64spec_reset(void);
void c64lib_64spec_assert_equal(uint8_t actual, uint8_t expected);
void c64lib_64spec_assert_not_equal(uint8_t actual, uint8_t expected);
void c64lib_64spec_assert_unsigned_less(uint8_t actual, uint8_t expected);
void c64lib_64spec_assert_unsigned_less_or_equal(uint8_t actual, uint8_t expected);
void c64lib_64spec_assert_unsigned_greater(uint8_t actual, uint8_t expected);
void c64lib_64spec_assert_unsigned_greater_or_equal(uint8_t actual, uint8_t expected);
void c64lib_64spec_assert_mask_set(uint8_t actual, uint8_t mask);
void c64lib_64spec_assert_mask_clear(uint8_t actual, uint8_t mask);
void c64lib_64spec_assert_bytes_equal(const uint8_t *actual, const uint8_t *expected, uint16_t count);
void c64lib_64spec_assert_bytes_not_equal(const uint8_t *actual, const uint8_t *expected, uint16_t count);
void c64lib_64spec_finish(void);
extern volatile C64lib64specResult c64lib_64spec_result;
#endif

c64lib/bitmap.h

Official six-byte c64lib bitmap tile-configuration layout adapted for C.

Included headers: <stdint.h>.

Structs:

Macros:

Header listing:

#ifndef WEB64_C64LIB_BITMAP_H
#define WEB64_C64LIB_BITMAP_H
#include <stdint.h>
#define C64LIB_BITMAP_TILE_CONFIG_SIZE 6
typedef struct {
    uint8_t tile_width;
    uint8_t tile_height;
    uint8_t left;
    uint8_t right;
    uint8_t top;
    uint8_t bottom;
} C64libBitmapTileConfig;
#endif

c64lib/chipset.h

Web64-native c64lib CIA, memory-banking, raster, VIC-II, and sprite compatibility declarations.

Included headers: <stdint.h>.

Functions:

Macros:

Header listing:

#ifndef WEB64_C64LIB_CHIPSET_H
#define WEB64_C64LIB_CHIPSET_H
#include <stdint.h>
#define C64LIB_RAM_RAM_RAM 0
#define C64LIB_RAM_CHAR_RAM 1
#define C64LIB_RAM_CHAR_KERNAL 2
#define C64LIB_BASIC_CHAR_KERNAL 3
#define C64LIB_RAM_IO_RAM 5
#define C64LIB_RAM_IO_KERNAL 6
#define C64LIB_BASIC_IO_KERNAL 7
#define C64LIB_BANK_0 3
#define C64LIB_BANK_1 2
#define C64LIB_BANK_2 1
#define C64LIB_BANK_3 0
#define C64LIB_STANDARD_TEXT_MODE 0
#define C64LIB_MULTICOLOR_TEXT_MODE 1
#define C64LIB_STANDARD_BITMAP_MODE 2
#define C64LIB_MULTICOLOR_BITMAP_MODE 3
#define C64LIB_EXTENDED_TEXT_MODE 4
#define C64LIB_IRQ_LIGHTPEN 8
#define C64LIB_IRQ_SPRITE_SPRITE 4
#define C64LIB_IRQ_SPRITE_BACKGROUND 2
#define C64LIB_IRQ_RASTER 1
#define C64LIB_JOY_UP 1
#define C64LIB_JOY_DOWN 2
#define C64LIB_JOY_LEFT 4
#define C64LIB_JOY_RIGHT 8
#define C64LIB_JOY_FIRE 16
#define C64LIB_TEXT_OFFSET(x, y) ((uint16_t)(x) + ((uint16_t)(y) * 40u))
#define C64LIB_TEXT_MEMORY(screen_slot, charset_slot) ((uint8_t)(((screen_slot) << 4) | ((charset_slot) << 1)))
#define C64LIB_BITMAP_MEMORY(screen_slot, bitmap_slot) ((uint8_t)(((screen_slot) << 4) | ((bitmap_slot) << 3)))
void c64lib_set_vic_bank(uint8_t bank);
void c64lib_disable_cia_interrupts(void);
void c64lib_configure_memory(uint8_t config);
void c64lib_set_raster(uint16_t raster);
uint8_t c64lib_detect_ntsc(void);
void c64lib_sprite_set_x(uint8_t sprite, uint16_t x);
void c64lib_sprite_set_y(uint8_t sprite, uint8_t y);
void c64lib_sprite_set_position(uint8_t sprite, uint16_t x, uint8_t y);
#endif

c64lib/common.h

Web64-native c64lib memory copy, fill, RLE, and optional Exomizer P39 compatibility routines.

Included headers: <stdint.h>, <stddef.h>.

Functions:

Macros:

Header listing:

#ifndef WEB64_C64LIB_COMMON_H
#define WEB64_C64LIB_COMMON_H
#include <stdint.h>
#include <stddef.h>
#define WEB64_C64LIB_COMPAT_VERSION 2
void c64lib_decompress_rle(const uint8_t *source, uint8_t *destination);
/* Decrunches a backward Exomizer 3.1.2 P39 mem stream. source_end points one byte past the stream. */
void c64lib_exomizer_decrunch(const uint8_t *source_end);
void c64lib_copy_large_forward(const void *source, void *destination, uint16_t count);
void c64lib_copy_large_backward(const void *source, void *destination, uint16_t count);
void c64lib_fill_memory(void *destination, uint8_t value, uint16_t count);
void c64lib_fill_screen(void *destination, uint8_t value);
void c64lib_rotate_memory_right(void *address, uint8_t count);
#endif

c64lib/copper64.h

Adapted copper64 four-byte display-list entries, handler identifiers, and start/stop routines.

Included headers: <stdint.h>.

Structs:

Macros:

Header listing:

#ifndef WEB64_C64LIB_COPPER64_H
#define WEB64_C64LIB_COPPER64_H
#include <stdint.h>
#define C64LIB_IRQH_BORDER_COL 1
#define C64LIB_IRQH_BG_COL_0 2
#define C64LIB_IRQH_BG_COL_1 3
#define C64LIB_IRQH_BG_COL_2 4
#define C64LIB_IRQH_BG_COL_3 5
#define C64LIB_IRQH_BORDER_BG_0_COL 6
#define C64LIB_IRQH_BORDER_BG_0_DIFF 7
#define C64LIB_IRQH_MEM_BANK 8
#define C64LIB_IRQH_MODE_MEM 9
#define C64LIB_IRQH_JSR 10
#define C64LIB_IRQH_MODE_HIRES_BITMAP 11
#define C64LIB_IRQH_MODE_MULTIC_BITMAP 12
#define C64LIB_IRQH_MODE_HIRES_TEXT 13
#define C64LIB_IRQH_MODE_MULTIC_TEXT 14
#define C64LIB_IRQH_MODE_EXTENDED_TEXT 15
#define C64LIB_IRQH_FULL_RASTER_BAR 16
#define C64LIB_IRQH_BG_RASTER_BAR 17
#define C64LIB_IRQH_HSCROLL 18
#define C64LIB_IRQH_HSCROLL_MAP 19
#define C64LIB_IRQH_MEMORY_CONTROL 20
#define C64LIB_IRQH_VSCROLL 21
#define C64LIB_IRQH_VSCROLL_NTSC 22
#define C64LIB_IRQH_SKIP 0
#define C64LIB_IRQH_LOOP 255
typedef struct { uint8_t control; uint8_t raster; uint8_t arg1; uint8_t arg2; } C64libCopperEntry;
void c64lib_copper_start(const C64libCopperEntry *list);
void c64lib_copper_stop(void);
#endif

c64lib/magic-desk.h

Magic Desk cartridge target, bank-selection, and browser-native loader declarations.

Included headers: <stdint.h>.

Functions:

Macros:

Header listing:

#ifndef WEB64_C64LIB_MAGIC_DESK_H
#define WEB64_C64LIB_MAGIC_DESK_H
#include <stdint.h>
#define C64LIB_MAGIC_DESK_BANK_SELECT 0xde00u
#define C64LIB_MAGIC_DESK_WINDOW 0x8000u
#define C64LIB_MAGIC_DESK_BANK_SIZE 0x2000u
#define C64LIB_MAGIC_DESK_CARTRIDGE_TYPE 19u
void c64lib_magic_desk_set_target(void *target);
void c64lib_magic_desk_copy(uint8_t first_bank, uint16_t size);
#define c64lib_magic_desk_load c64lib_magic_desk_copy
#endif

c64lib/sprites.h

c64lib-compatible sprite register-address and mask helpers over the Web64 chipset module.

Included headers: <c64lib/chipset.h>.

Macros:

Header listing:

#ifndef WEB64_C64LIB_SPRITES_H
#define WEB64_C64LIB_SPRITES_H
#include <c64lib/chipset.h>
#define C64LIB_SPRITE_MASK(sprite) ((uint8_t)(1u << (sprite)))
#define C64LIB_SPRITE_X_REGISTER(sprite) ((volatile uint8_t*)(0xd000u + ((uint16_t)(sprite) * 2u)))
#define C64LIB_SPRITE_Y_REGISTER(sprite) ((volatile uint8_t*)(0xd001u + ((uint16_t)(sprite) * 2u)))
#define C64LIB_SPRITE_COLOR_REGISTER(sprite) ((volatile uint8_t*)(0xd027u + (sprite)))
#endif

c64lib/text.h

Web64-native c64lib text, hexadecimal output, scrolling, and stateful 2x2 Tile2 routines.

Included headers: <stdint.h>.

Functions:

Structs:

Header listing:

#ifndef WEB64_C64LIB_TEXT_H
#define WEB64_C64LIB_TEXT_H
#include <stdint.h>
void c64lib_text_putxy(const char *text, uint8_t x, uint8_t y, uint8_t color);
void c64lib_text_hex8(uint8_t value, uint8_t x, uint8_t y, uint8_t color);
void c64lib_increment_text(uint8_t *text, uint8_t count, uint8_t increment);
void c64lib_copy_screen_block(const uint8_t *source, uint8_t width, uint8_t height, uint16_t screen_target, const uint8_t *color_source, uint16_t color_target);
void c64lib_scroll1x1(uint16_t screen_address);
void c64lib_shift_left(uint16_t address, uint8_t start_row, uint8_t end_row);
void c64lib_shift_right(uint16_t address, uint8_t start_row, uint8_t end_row);
void c64lib_shift_up(uint16_t address, uint8_t start_row, uint8_t end_row);
void c64lib_shift_down(uint16_t address, uint8_t start_row, uint8_t end_row);
void c64lib_draw_tile2(const uint8_t *characters, uint16_t screen_address, uint16_t color_address, uint8_t color);
typedef struct {
    const uint8_t *map;
    const uint8_t *tile_planes;
    const uint8_t *block_colors;
    const uint8_t *block_materials;
    const uint8_t *map_colors;
    const uint8_t *map_materials;
    uint8_t *screen;
    uint8_t *color_ram;
    uint8_t *row_offsets_lo;
    uint8_t *row_offsets_hi;
    uint8_t map_width;
    uint8_t map_height;
    uint8_t screen_width;
    uint8_t screen_height;
    uint8_t start_row;
    uint8_t end_row;
    uint16_t map_x;
    uint16_t map_y;
    uint8_t default_color;
} C64libTile2Config;
void c64lib_tile2_init(const C64libTile2Config *config);
void c64lib_tile2_render(void);
void c64lib_tile2_scroll_left(void);
void c64lib_tile2_scroll_right(void);
void c64lib_tile2_scroll_up(void);
void c64lib_tile2_scroll_down(void);
uint8_t c64lib_tile2_material_at(uint8_t x, uint8_t y);
#endif

c64lib/vic2.h

c64lib-compatible VIC-II register names mapped to the typed Web64 C64 header.

Included headers: <c64lib/chipset.h>, <c64.h>.

Macros:

Header listing:

#ifndef WEB64_C64LIB_VIC2_H
#define WEB64_C64LIB_VIC2_H
#include <c64lib/chipset.h>
#include <c64.h>
#define C64LIB_VIC2 VIC_BASE
#define C64LIB_RASTER VIC_RASTER
#define C64LIB_CONTROL_1 VIC_CONTROL1
#define C64LIB_CONTROL_2 VIC_CONTROL2
#define C64LIB_MEMORY_CONTROL VIC_MEMORY_CONTROL
#define C64LIB_BORDER_COLOR VIC_BORDER
#define C64LIB_BACKGROUND_COLOR_0 VIC_BACKGROUND0
#endif

cbm.h

Dependency-linked low-level KERNAL channel, load, save, and status wrappers.

Included headers: <stdint.h>, <c64.h>.

Functions:

Macros:

Header listing:

#ifndef WEB64_CBM_H
#define WEB64_CBM_H
#include <stdint.h>
#include <c64.h>
#define CHRIN KERNAL_CHRIN
#define CHROUT KERNAL_CHROUT
#define GETIN KERNAL_GETIN
#define READST KERNAL_READST
#define LOAD KERNAL_LOAD
#define SAVE KERNAL_SAVE
#define SETLFS KERNAL_SETLFS
#define SETNAM KERNAL_SETNAM
#define OPEN KERNAL_OPEN
#define CLOSE KERNAL_CLOSE
#define CHKIN KERNAL_CHKIN
#define CHKOUT KERNAL_CHKOUT
#define CLRCHN KERNAL_CLRCHN
uint8_t cbm_k_readst(void);
/* 0 on success; otherwise 0x0100 | KERNAL A (including STOP code 0). */
uint16_t cbm_k_last_error(void);
void cbm_k_setlfs(uint8_t logical_file, uint8_t device, uint8_t secondary);
void cbm_k_setnam(const char *name, uint8_t length);
uint8_t cbm_k_open(void);
void cbm_k_close(uint8_t logical_file);
uint8_t cbm_k_chkin(uint8_t logical_file);
uint8_t cbm_k_chkout(uint8_t logical_file);
void cbm_k_clrchn(void);
uint8_t cbm_k_chrin(void);
void cbm_k_chrout(uint8_t value);
uint16_t cbm_k_load(uint8_t verify, uint16_t address);
uint8_t cbm_k_save(uint16_t start_address, uint16_t end_address);
#endif

conio.h

cc65-style screen and text helpers mapped onto the Web64 SDK surface.

Included headers: <stdint.h>, <c64.h>, <web64.h>.

Functions:

Macros:

Header listing:

#ifndef WEB64_CONIO_H
#define WEB64_CONIO_H
#include <stdint.h>
#include <c64.h>
#include <web64.h>
#define COLOR_BLACK VIC_COLOR_BLACK
#define COLOR_WHITE VIC_COLOR_WHITE
#define COLOR_RED VIC_COLOR_RED
#define COLOR_CYAN VIC_COLOR_CYAN
#define COLOR_PURPLE VIC_COLOR_PURPLE
#define COLOR_GREEN VIC_COLOR_GREEN
#define COLOR_BLUE VIC_COLOR_BLUE
#define COLOR_YELLOW VIC_COLOR_YELLOW
#define COLOR_ORANGE VIC_COLOR_ORANGE
#define COLOR_BROWN VIC_COLOR_BROWN
#define COLOR_LIGHTRED VIC_COLOR_LIGHT_RED
#define COLOR_GRAY1 VIC_COLOR_DARK_GRAY
#define COLOR_GRAY2 VIC_COLOR_GRAY
#define COLOR_LIGHTGREEN VIC_COLOR_LIGHT_GREEN
#define COLOR_LIGHTBLUE VIC_COLOR_LIGHT_BLUE
#define COLOR_GRAY3 VIC_COLOR_LIGHT_GRAY
extern _fastcall int cputc(int ch);
extern _fastcall int cputs(char *text);
extern _fastcall int textcolor(int color);
extern _fastcall int bordercolor(int color);
extern _fastcall int bgcolor(int color);
extern _fastcall int wherex(void);
extern _fastcall int wherey(void);
extern _fastcall int cputhex8(int value);
#define CH_ENTER 13
#define CH_ESC 27
#define CH_DEL 20
#define CH_CURS_LEFT 157
#define CH_CURS_RIGHT 29
#define CH_CURS_UP 145
#define CH_CURS_DOWN 17
#endif

ctype.h

ASCII-oriented character classification and case-conversion declarations backed by the Web64 runtime.

Functions:

Header listing:

#ifndef WEB64_CTYPE_H
#define WEB64_CTYPE_H
/* Web64 tiny ctype parameter: c is the byte character/classification value in A for _fastcall calls. */
extern _fastcall int isdigit(int c);
extern _fastcall int isalnum(int c);
extern _fastcall int isalpha(int c);
extern _fastcall int iscntrl(int c);
extern _fastcall int isspace(int c);
extern _fastcall int isgraph(int c);
extern _fastcall int islower(int c);
extern _fastcall int isprint(int c);
extern _fastcall int ispunct(int c);
extern _fastcall int isupper(int c);
extern _fastcall int isxdigit(int c);
extern _fastcall int tolower(int c);
extern _fastcall int toupper(int c);
#endif

float.h

Web64 SDK header <float.h>.

Macros:

Header listing:

#ifndef WEB64_FLOAT_H
#define WEB64_FLOAT_H
#define FLT_RADIX 2
#define FLT_ROUNDS 1
#define FLT_MANT_DIG 24
#define DBL_MANT_DIG 53
#define LDBL_MANT_DIG 53
#define FLT_DIG 6
#define DBL_DIG 15
#define LDBL_DIG 15
#define FLT_MIN_EXP (-125)
#define DBL_MIN_EXP (-1021)
#define LDBL_MIN_EXP (-1021)
#define FLT_MIN_10_EXP (-37)
#define DBL_MIN_10_EXP (-307)
#define LDBL_MIN_10_EXP (-307)
#define FLT_MAX_EXP 128
#define DBL_MAX_EXP 1024
#define LDBL_MAX_EXP 1024
#define FLT_MAX_10_EXP 38
#define DBL_MAX_10_EXP 308
#define LDBL_MAX_10_EXP 308
#define FLT_MAX 3.402823466e+38F
#define DBL_MAX 1.7976931348623157e+308
#define LDBL_MAX 1.7976931348623157e+308L
#define FLT_EPSILON 1.192092896e-7F
#define DBL_EPSILON 2.2204460492503131e-16
#define LDBL_EPSILON 2.2204460492503131e-16L
#define FLT_MIN 1.175494351e-38F
#define DBL_MIN 2.2250738585072014e-308
#define LDBL_MIN 2.2250738585072014e-308L
#endif

joy.h

Minimal joystick helper for reading the active C64 port state.

Included headers: <stdint.h>, <c64.h>.

Functions:

Header listing:

#ifndef WEB64_JOY_H
#define WEB64_JOY_H
#include <stdint.h>
#include <c64.h>
uint8_t joy_read(void);
#endif

joystick.h

cc65-familiar joystick constants and helpers without native driver loading.

Included headers: <stdint.h>, <c64.h>.

Functions:

Macros:

Header listing:

#ifndef WEB64_JOYSTICK_H
#define WEB64_JOYSTICK_H
#include <stdint.h>
#include <c64.h>
#define JOY_1 1
#define JOY_2 2
#define JOY_BTN_1 JOY_FIRE
/* Raw active-low CIA sample: zero input bit = pressed; one = released. */
/* Use JOY_1 or JOY_2. Example: uint8_t joy = web64_joy_read(JOY_2); */
/* if ((joy & JOY_FIRE) == 0) { ... }  JOY_LEFT/JOY_RIGHT use the same test. */
extern _fastcall uint8_t joy_read(uint8_t port);
extern _fastcall uint8_t web64_joy_read(uint8_t port);
#endif

libc.h

Aggregate convenience header over the dependency-linked Web64 standard library surface.

Included headers: <stddef.h>, <stdio.h>, <stdlib.h>, <string.h>, <ctype.h>.

Macros:

Header listing:

#ifndef WEB64_LIBC_H
#define WEB64_LIBC_H
/* Web64 aggregate convenience header. Implementations are linked only when called. */
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#define INT_MAX 0x7fff
#define INT_MIN 0x8000
#endif

limits.h

Web64 SDK header <limits.h>.

Macros:

Header listing:

#ifndef WEB64_LIMITS_H
#define WEB64_LIMITS_H
#define CHAR_BIT 8
#define SCHAR_MIN (-127-1)
#define SCHAR_MAX 127
#define UCHAR_MAX 255U
#define CHAR_MIN SCHAR_MIN
#define CHAR_MAX SCHAR_MAX
#define MB_LEN_MAX 1
#define SHRT_MIN (-32767-1)
#define SHRT_MAX 32767
#define USHRT_MAX 65535U
#define INT_MIN (-32767-1)
#define INT_MAX 32767
#define UINT_MAX 65535U
#define LONG_MIN (-2147483647L-1L)
#define LONG_MAX 2147483647L
#define ULONG_MAX 4294967295UL
#endif

peekpoke.h

PEEK/POKE helper macros for byte and word memory access.

Included headers: <stdint.h>.

Macros:

Header listing:

#ifndef WEB64_PEEKPOKE_H
#define WEB64_PEEKPOKE_H
#include <stdint.h>
#define PEEK(address) (*(volatile uint8_t*)(address))
#define POKE(address, value) (*(volatile uint8_t*)(address) = (uint8_t)(value))
#define PEEKW(address) (*(volatile uint16_t*)(address))
#define POKEW(address, value) (*(volatile uint16_t*)(address) = (uint16_t)(value))
#endif

sprite.h

Small sprite helper API for position, color, and enable writes.

Included headers: <stdint.h>, <c64.h>.

Functions:

Header listing:

#ifndef WEB64_SPRITE_H
#define WEB64_SPRITE_H
#include <stdint.h>
#include <c64.h>
void sprite_set_pos(uint8_t sprite_id, uint16_t x, uint8_t y);
void sprite_enable(uint8_t mask);
void sprite_set_color(uint8_t sprite_id, uint8_t color);
#endif

stdarg.h

Web64 SDK header <stdarg.h>.

Functions:

Macros:

Header listing:

#ifndef WEB64_STDARG_H
#define WEB64_STDARG_H
typedef unsigned char *va_list;
void __web64_va_start(va_list ap, void *last);
unsigned long __web64_va_arg(va_list ap, unsigned int size);
void __web64_va_end(va_list ap);
#define va_start(ap, last) __web64_va_start(ap, last)
#define va_arg(ap, type) ((type)__web64_va_arg(ap, sizeof(type)))
#define va_end(ap) __web64_va_end(ap)
#endif

stdbool.h

Boolean language aliases and constants.

Macros:

Header listing:

#ifndef WEB64_STDBOOL_H
#define WEB64_STDBOOL_H
#define bool _Bool
#define true 1
#define false 0
#define __bool_true_false_are_defined 1
#endif

stddef.h

Core pointer-sized typedefs and NULL.

Typedefs:

Macros:

Header listing:

#ifndef WEB64_STDDEF_H
#define WEB64_STDDEF_H
typedef unsigned int size_t;
typedef signed int ptrdiff_t;
typedef unsigned int wchar_t;
#define NULL ((void*)0)
#define offsetof(type, member) ((size_t)&(((type*)0)->member))
#endif

stdint.h

Fixed-width integer typedefs and limit macros.

Typedefs:

Macros:

Header listing:

#ifndef WEB64_STDINT_H
#define WEB64_STDINT_H
typedef unsigned char uint8_t;
typedef unsigned int uint16_t;
typedef unsigned long uint32_t;
typedef signed char int8_t;
typedef signed int int16_t;
typedef signed long int32_t;
typedef int16_t intptr_t;
typedef uint16_t uintptr_t;
typedef int32_t intmax_t;
typedef uint32_t uintmax_t;
typedef int8_t int_least8_t;
typedef uint8_t uint_least8_t;
typedef int16_t int_least16_t;
typedef uint16_t uint_least16_t;
typedef int32_t int_least32_t;
typedef uint32_t uint_least32_t;
typedef int8_t int_fast8_t;
typedef uint8_t uint_fast8_t;
typedef int16_t int_fast16_t;
typedef uint16_t uint_fast16_t;
typedef int32_t int_fast32_t;
typedef uint32_t uint_fast32_t;
#define INT8_MIN 0x80
#define INT8_MAX 0x7f
#define UINT8_MAX 0xff
#define INT16_MIN 0x8000
#define INT16_MAX 0x7fff
#define UINT16_MAX 0xffff
#define UINT32_MAX 0xffffffffUL
#endif

stdio.h

Tiny stdio surface: blocking raw-byte getchar, putchar, puts, and compiler-lowered literal printf.

Functions:

Macros:

Header listing:

#ifndef WEB64_STDIO_H
#define WEB64_STDIO_H
#define EOF 0xffff
/* Web64 tiny stdio surface: getchar/putchar/puts are runtime calls; printf is compiler-lowered for literal formats with %d values. */
extern _fastcall int getchar(void);
extern _fastcall int putchar(int c);
extern _fastcall int puts(const char *str);
extern int printf(const char *format, ...);
#endif

stdlib.h

Tiny stdlib surface: abs, atoi, rand, srand, and abort.

Functions:

Macros:

Header listing:

#ifndef WEB64_STDLIB_H
#define WEB64_STDLIB_H
#define RAND_MAX 0x00ff
/* Web64 tiny stdlib parameters: j=value, s=C string pointer, seed=byte random seed. */
extern int abs(int j);
extern int atoi(const char *s);
extern _fastcall int rand(void);
extern _fastcall void srand(unsigned int seed);
void abort(void);
#endif

string.h

Byte and C-string manipulation declarations backed by the Web64 runtime.

Included headers: <stddef.h>.

Functions:

Header listing:

#ifndef WEB64_STRING_H
#define WEB64_STRING_H
#include <stddef.h>
/* Web64 tiny string runtime parameters: s/s1=destination pointer, s2=source/search pointer, c=byte value, n=count. */
extern void *memchr(const void *s, int c, size_t n);
extern int memcmp(const void *s1, const void *s2, size_t n);
extern void *memcpy(void *s1, const void *s2, size_t n);
extern void *memmove(void *s1, const void *s2, size_t n);
extern void *memset(void *s, int c, size_t n);
extern char *strcat(char *s1, const char *s2);
extern char *strchr(const char *s, int c);
extern int strcmp(const char *s1, const char *s2);
extern char *strcpy(char *s1, const char *s2);
extern size_t strcspn(const char *s1, const char *s2);
extern size_t strlen(const char *s);
extern char *strncat(char *s1, const char *s2, size_t n);
extern int strncmp(const char *s1, const char *s2, size_t n);
extern char *strncpy(char *s1, const char *s2, size_t n);
extern char *strpbrk(const char *s1, const char *s2);
extern char *strrchr(const char *s, int c);
extern size_t strspn(const char *s1, const char *s2);
extern char *strstr(const char *s1, const char *s2);
#endif

web64.h

General Web64 SDK helpers for timing, text, randomness, simple drawing, and zero-parameter void calls by address.

Included headers: <stdint.h>, <c64.h>.

Functions:

Macros:

Header listing:

#ifndef WEB64_CORE_H
#define WEB64_CORE_H
#include <stdint.h>
#include <c64.h>
#define VoidCall(addr) (*(void (*)(void))(addr))()
#define CURSOFF() (*(volatile uint8_t*)0x00cc = 1)
#define CURSON() (*(volatile uint8_t*)0x00cc = 0)
void delay_frames(uint8_t frames);
void delay_ms(uint16_t milliseconds);
uint8_t random8(void);
void clrscr(void);
void gotoxy(uint8_t x, uint8_t y);
void cprintf(const char *text);
void plot_pixel(uint16_t address, uint8_t value);
#endif

web64/actor-batch.h

Open caller-owned actor SoA phases, pair/visible/command buffers, direct and mux adapters, fused prepared pipeline, and checked/fast entry points.

Included headers: <web64/actors.h>, <web64/sprite-mux.h>.

Functions: