C64_SKILLS/.ai/skills/basic-v2-bridge/SKILL.md

Skill: BASIC V2 Bridge — SYS, USR, PEEK, POKE, and BASIC Internals

Use this skill when

The task involves BASIC V2, calling assembly from BASIC, calling BASIC ROM routines from assembly, SYS, USR, PEEK, POKE, WAIT, tokenization, variable storage, or BASIC program layout.

Core concepts

• BASIC V2 is interpreted. Each statement is parsed and executed at runtime, which is why BASIC is slower than ML.
• BASIC program lines are tokenized and linked in memory.
• BASIC and ML can cooperate if memory ownership is clear.
• SYS calls an ML routine as a command.
• USR(x) calls an ML routine as a function-like expression.
• PEEK reads one byte; POKE writes one byte.

Calling ML with SYS

BASIC:

10 SYS 49152

Assembly routine at $C000 must normally end with:

rts

Passing registers through SYS

Before SYS, BASIC can place values in these locations:

Decimal	Hex	Register
780	$030C	Accumulator A
781	$030D	X register
782	$030E	Y register
783	$030F	Processor status

Example:

10 POKE 780,65:REM A = PETSCII "A"
20 SYS 49152
30 PRINT PEEK(780)

Calling ML with USR

USR(x) is best when an ML routine should behave like a function.

Use cases:

• Fast math helper.
• Custom string/numeric function.
• BASIC extension experiments.

Cautions:

• USR uses BASIC floating-point accumulator conventions.
• It is more complex than SYS; use SYS first unless function syntax is needed.

BASIC pointers worth knowing

Decimal	Hex	Meaning
43-44	$002B-$002C	Start of BASIC text
45-46	$002D-$002E	End of BASIC text
47-48	$002F-$0030	Start of variables
49-50	$0031-$0032	Start of arrays
51-52	$0033-$0034	End of arrays/start of strings
55-56	$0037-$0038	Top of BASIC memory

BASIC patterns

Change border and background

10 POKE 53280,6:REM BORDER $D020
20 POKE 53281,0:REM BACKGROUND $D021

Write to screen and color RAM

10 POKE 1024,1:REM SCREEN CODE A
20 POKE 55296,2:REM COLOR RED IN LOW NYBBLE

Protect ML at $C000 with simple convention

For many C64 BASIC programs, $C000 is outside normal BASIC RAM. Still, document the assumption and avoid loaders that extend into $C000.

Agent checklist

When producing BASIC+ML examples:

1. Give a BASIC loader if the user needs type-in code.
2. Give the assembly source separately when possible.
3. Include exact SYS address.
4. Ensure ML routine ends in RTS.
5. Explain which locations are POKEd and why.