mattiashz/c65gm

Fork 0

Mattias Hansson 104e950d63 Updated docs to describe new SCRIPT blocks including macros

2026-02-11 14:06:09 +01:00

11 KiB

Raw Blame History

Syntax Reference

Comments

C65GM uses C-style line comments.

Syntax:

// <comment text>

Examples:

BYTE counter = 0    // Initialize counter
// This is a full line comment
FOR i = 0 TO 10     // Loop through values
    counter++       // Increment
NEXT

Notes:

Comments start with // and continue to end of line
Comments in ASM blocks use assembly syntax: ;
Comments in SCRIPT blocks use Starlark syntax: #

Preprocessor Directives

#DEFINE

Defines a text substitution macro.

Syntax:

#DEFINE <n> [= <value>]

Examples:

#DEFINE MAX_SPEED = 10
#DEFINE HELLO = GOODBYE // Will replace the text HELLO in all source with GOODBYE (except ASM and SCRIPT blocks)
#DEFINE HELLO2 = GOOOOOODBYE // Longest match wins. If HELLO2 is encountered this will be the match not the HELLO define above 
#DEFINE SCREEN = $$0400 // Notice $$, see below.
#DEFINE OFFSET = 255

Note: Replacements are not recursive. Once a match is found, it's replaced, and processing starts after the replacement.

Special Characters in Values:

Define values support $ escape sequences for special characters:

$XX (two hex digits) = character with code XX
$$ = literal $ character

#DEFINE SPACE = $20          // space character
#DEFINE NEWLINE = $0D        // carriage return
#DEFINE TAB = $09            // tab character
#DEFINE HEXADDR = $$D020     // stores "$D020" as text

Notes:

Optional = separator
Value can contain previously defined macros
Macros are expanded in source lines
Case sensitive
$ escapes are processed when the define is created, not when used
For most purposes, use WORD CONST or BYTE CONST instead of preprocessor defines to define constant named values

#UNDEF

Undefines a previously defined macro.

Syntax:

#UNDEF <n>

Examples:

#DEFINE DEBUG = 1
#UNDEF DEBUG

#IFDEF

Conditional compilation if macro is defined.

Syntax:

#IFDEF <n>

Examples:

#IFDEF DEBUG
    BYTE debugFlag = 1
#IFEND

#IFDEF PAL
    BYTE scanlines = 312
#IFEND

#IFNDEF

Conditional compilation if macro is not defined.

Syntax:

#IFNDEF <n>

Examples:

#IFNDEF __INCLUDED_SPRITE_LIB
    #DEFINE __INCLUDED_SPRITE_LIB = 1
    FUNC drawSprite
        ; sprite code
    FEND
#IFEND

Notes:

Common pattern for include guards
Prevents multiple inclusion

#IFEND

Ends conditional compilation block.

Syntax:

#IFEND

Examples:

See #IFDEF and #IFNDEF

#INCLUDE

Includes another source file.

Syntax:

#INCLUDE <filename>
#INCLUDE <libfile>

Examples:

#INCLUDE sprites.c65
#INCLUDE lib/math.c65
#INCLUDE "constants.c65"
#INCLUDE <stdlib.c65>

Notes:

Relative path: resolves relative to current file
Angle brackets <file>: searches in library path defined by C65LIBPATH environment variable
Supports nested includes
Use with #IFNDEF for include guards

#PRINT

Prints message during compilation.

Syntax:

#PRINT <message>

Examples:

#PRINT Compiling main module
#PRINT MAX_VALUE
#PRINT Debug build enabled

Notes:

Useful for debugging preprocessor
Macros expanded before printing

#HALT

Stops compilation immediately.

Syntax:

#HALT

Examples:

#IFDEF INCOMPLETE
    #PRINT Feature not implemented
    #HALT
#IFEND

Notes:

Halts entire compilation process, not just preprocessing
Returns exit code 2

#PRAGMA

Sets compiler pragmas (options).

Syntax:

#PRAGMA <n> [<value>]

Available Pragmas:

_P_USE_LONG_JUMP

Uses JMP instead of branch instructions for IF/WHILE/FOR
Needed when branch targets exceed 127 byte range
Value: any non-zero value enables

_P_USE_IMMUTABLE_CODE

Prevents self-modifying code generation
Required for ROM-based code
Errors on PEEK/POKE/GOSUB with variable addresses

_P_USE_CBM_STRINGS

Encodes strings in CBM PETSCII format
Default: ASCII encoding
Value: any non-empty value enables

Examples:

#PRAGMA _P_USE_LONG_JUMP 1
#PRAGMA _P_USE_IMMUTABLE_CODE 1
#PRAGMA _P_USE_IMMUTABLE_CODE 0 //turn off pragma
#PRAGMA _P_USE_CBM_STRINGS 1

Code Blocks

ASM...ENDASM

Inline assembly code block.

Syntax:

ASM
    <assembly code>
ENDASM

Examples:

ASM
    lda #$00
    sta $d020
    jsr $ffd2
ENDASM

BYTE temp = 5
ASM
    lda temp
    clc
    adc #10
    sta temp
ENDASM

FUNC calculate(value)
    BYTE local = 10
    ASM
        lda |local|        ; Reference local variable
        clc
        adc value
        sta |local|
    ENDASM
FEND

Notes:

Assembly code passed through to ACME assembler unchanged
Can reference global variables by name
Local variables inside FUNC must use |varname| syntax
Comments in ASM blocks use ; (assembly syntax)
No macro expansion inside ASM blocks

SCRIPT...ENDSCRIPT

Starlark script code block for generating assembly code.

Scripts are written in Starlark (Python-like language) and executed at compile time. Output from print() statements is fed directly into the assembler.

Syntax:

SCRIPT
    <starlark code>
ENDSCRIPT

Examples:

Simple data generation:

SCRIPT
    for i in range(256):
        print("    !8 %d" % i)
ENDSCRIPT

Sine table generation:

SCRIPT
    import math
    print("sintable:")
    for i in range(256):
        angle = (i * 2.0 * math.pi) / 256.0
        sine = math.sin(angle)
        value = int((sine + 1.0) * 127.5)
        print("    !8 %d" % value)
ENDSCRIPT

Using compiler variables:

BYTE tableSize = 64

SCRIPT
    # Reference variables in generated assembly
    print("lookup:")
    for i in range(64):
        print("    !8 %d" % (i * 2))
    print("    ; Table size is stored in |tableSize|")
ENDSCRIPT

Notes:

Scripts use Starlark language (Python-like subset)
Comments in SCRIPT blocks use # (Python syntax)
Output from print() goes directly to assembler
Can reference compiler variables using |varname| syntax
Math module available: import math
Maximum 1 million execution steps (prevents infinite loops)
Executed at compile time, not runtime

SCRIPT LIBRARY...ENDSCRIPT

Defines reusable Starlark functions that persist across all subsequent SCRIPT blocks.

Syntax:

SCRIPT LIBRARY
    <starlark function definitions>
ENDSCRIPT

Examples:

Defining reusable functions:

SCRIPT LIBRARY
def emit_nops(count):
  for i in range(count):
    print("  nop")

def emit_delay(cycles):
  for i in range(cycles // 4):
    print("  nop")
    print("  nop")
  remainder = cycles % 4
  if remainder >= 3:
    print("  bit $ea")
    remainder -= 3
  for i in range(remainder // 2):
    print("  nop")
ENDSCRIPT

Using library functions in SCRIPT blocks:

SCRIPT
  emit_nops(5)
  emit_delay(10)
ENDSCRIPT

Notes:

Functions defined in SCRIPT LIBRARY are available to all subsequent SCRIPT, SCRIPT LIBRARY, and SCRIPT MACRO blocks
Multiple SCRIPT LIBRARY blocks accumulate - later blocks can use functions from earlier ones
Typically placed in include files for reuse across projects
The library block itself can also use print() to emit code, but this is uncommon

SCRIPT MACRO...ENDSCRIPT

Defines a named, parameterized macro that expands inline when invoked.

Syntax:

SCRIPT MACRO name(param1, param2, ...)
    <starlark code>
ENDSCRIPT

Invocation:

@name(arg1, arg2, ...)           // Outside ASM blocks
|@name(arg1, arg2, ...)|         // Inside ASM blocks

Examples:

Defining macros:

SCRIPT MACRO delay(cycles)
  if cycles < 2:
    fail("Cannot delay less than 2 cycles")
  emit_delay(cycles)
ENDSCRIPT

SCRIPT MACRO set_irq(handler)
  print("  lda #<%s" % handler)
  print("  sta $fffe")
  print("  lda #>%s" % handler)
  print("  sta $ffff")
ENDSCRIPT

Invoking macros outside ASM blocks:

BYTE CONST CYCLES_PER_LINE = 63

@delay(10)
@delay(CYCLES_PER_LINE-20)
@set_irq(my_handler)

Invoking macros inside ASM blocks:

ASM
  lda #$00
  |@delay(8)|
  sta $d020
ENDASM

Parameter Types:

Integer expressions - Evaluated at compile time:
- Literal numbers: 10, $FF, %11110000
- Constants: CYCLES_PER_LINE, MAX_VALUE
- Arithmetic: CYCLES_PER_LINE-20, BASE+OFFSET
- Passed to macro as Starlark int
Labels/Identifiers - Passed as strings:
- Bare identifiers that don't resolve to constants: my_handler, loop_start
- Passed to macro as Starlark string
- Use in generated assembly: print(" jmp %s" % label)

Checking parameter types in macros:

SCRIPT MACRO flexible(value)
  if type(value) == "int":
    print("  lda #%d" % value)
  else:
    print("  lda %s" % value)
ENDSCRIPT

Error handling with fail():

SCRIPT MACRO delay(cycles)
  if cycles < 2:
    fail("Cannot delay less than 2 cycles")
  emit_delay(cycles)
ENDSCRIPT

The fail() function stops compilation with an error message pointing to the macro invocation site.

Notes:

Macros are NOT executed at definition time - only when invoked
Macros have access to all SCRIPT LIBRARY functions
print() output replaces the macro invocation site
Everything expands inline - no JSR/RTS overhead
Use for cycle-critical code like raster timing

Expression Syntax

Expressions evaluate left to right with no operator precedence.

Number Formats

Decimal:

Hexadecimal ($-prefix):

$FF
$D020
$C000
$00

Binary (%-prefix):

Operators

Evaluated strictly left to right:

+ Addition
- Subtraction
* Multiplication
/ Division
| Bitwise OR
& Bitwise AND
^ Bitwise XOR

Constants

Named constants defined with BYTE CONST or WORD CONST:

BYTE CONST MAX_SPEED = 10
WORD CONST SCREEN = $0400

speed = MAX_SPEED
pointer = SCREEN

Expression Examples

value = 100+50
result = $FF-10
address = $D000+32
mask = %11110000&$0F
combined = base|offset
calculated = start+length*2

Critical: No operator precedence. Evaluation is strictly left to right:

result = 2+3*4    ; evaluates as (2+3)*4 = 20, not 2+(3*4) = 14
value = $10|$20&$0F   ; evaluates as ($10|$20)&$0F, not $10|($20&$0F)

Usage Contexts

Expressions accepted anywhere a numeric literal is expected:

Variable initialization:

BYTE count = 10+5
WORD addr = $C000+$100

Absolute addresses:

BYTE screen @ $0400+40*10
INC $D000+20

Command parameters:

FOR i = 0 TO MAX_VALUE-1
IF x > THRESHOLD+10
POKE $D020+offset WITH value
result = PEEK $0400+index

Arithmetic operations:

sum = value1+value2
product = base*factor
adjusted = original+OFFSET

Limitations

No parentheses for grouping:

; NOT SUPPORTED:
result = (a+b)*c
value = base+(offset*2)

No nested expressions in assignments:

; NOT SUPPORTED:
x = y + z    ; only single value or constant expression
x = a+b      ; constant expression (no spaces) OK if a,b are constants

Workaround for complex expressions: Use temporary variables:

temp = a + b
result = temp - c

Constant Expressions

Expressions without spaces are treated as constant expressions:

value = 100+50       ; OK - constant expression
value = 100 + 50     ; ERROR - not a simple assignment
value = MAX+10       ; OK if MAX is constant

11 KiB Raw Blame History

Syntax Reference

Comments

Preprocessor Directives

#DEFINE

#UNDEF

#IFDEF

#IFNDEF

#IFEND

#INCLUDE

#PRINT

#HALT

#PRAGMA

Code Blocks

ASM...ENDASM

SCRIPT...ENDSCRIPT

SCRIPT LIBRARY...ENDSCRIPT

SCRIPT MACRO...ENDSCRIPT

Expression Syntax

Number Formats

Operators

Constants

Expression Examples

Usage Contexts

Limitations

Constant Expressions

11 KiB

Raw Blame History