Assembler - Pseudo Operations

These pseudo ops are supported in ACME/C64Studio mode:




!ADDRESS, !ADDR {

This pseudo is currently a noop added for ACME compatibility. Intention: Any labels declared inside are marked as being addresses and will throw a warning when used in immediate addressing opcodes.



!address { SCREEN_ADDRESS = $0400 }


!ALIGN <andvalue>,<equalvalue>[,<fillvalue>]

This pseudo op fills memory until a matching address is reached. Fill value is output until program counter and [andvalue] equal [equalvalue].
If [fillvalue] is omitted 0 is used.



!align 1,0 ;wait for even address !align 255,0 ;align code to page border


!BANK <bank index>[,<bank size>]

This pseudo op is for the support of cartridge banks. Any following assembled code is filled to the given bank size when the end of file or another !BANK pseudo op is encountered.

If the size argument is not used the size from a previous !BANK statement will be used.


Usually !BANK will be used in conjunction with a !PSEUDOPC.



!bank 0,$2000


!BASIC [,<jump address>]
!BASIC <line number>,<label>
!BASIC <line number>,<special/tokens,>,<label>

This pseudo op adds a BASIC start line with a sys call to either the given jump address or the first statement after the pseudo op. If not provided otherwise the added BASIC line always has line number 10 and a 4 digit target address. This way the BASIC line will always require 12 bytes. If the jump address is 5 decimal digits the line will use 13 bytes.

Note: If !cpu is set to m65 (Mega65) the !basic directive will add a line before the actual SYS call setting the bank to 0 (10 BANK 0). All other parts will be moved to the second line.

If a string comment is used it is appended directly after the SYS number.
Note: If no colon is added this will result in a syntax error when returning to BASIC.


Example #1 - standard, no parameters


*=$0801 ;12 bytes basic sys call !basic ;SYS call jumps here rts

BASIC listing looks like:


10 SYS2061

BASIC listing looks like for !cpu M65:


10 MODE0 20 SYS2061


Example #2 - start address


*=$0801 ;12 bytes basic sys call !basic init init ;SYS call jumps here rts

BASIC listing looks like:


10 SYS2061


Example #3 - line number and start address


*=$0801 ;12 bytes basic sys call !basic 2021, init init ;SYS call jumps here rts

BASIC listing looks like:


2021 SYS2061


Example #4 - full monty, line number, tokens/text and start address


*=$0801 ;29 bytes basic sys call ;sys call is followed by colon, a REM token, 4 backspaces to hide them during LIST, and the actual comment !basic 2021, ":", $8F, $14,$14,$14,$14, " MY COMMENT", init init ;SYS call jumps here rts

BASIC listing looks like:


2021 SYS2061 MY COMMENT


!BINARY, !BIN, !BI <file name>[,<size>,[<skip>]]

This pseudo op inserts a file as binary data.

<size> sets the number of bytes that are read from the file. If it is not set the whole file is included.

<skip> sets the number of bytes that are skipped from the start of the file. If it is not set no bytes are skipped.



!bin "soulless20.bin" !binary "music.prg",,2


!BYTE, !BY, !8, !08

This pseudo op allows to insert one ore more bytes at the current location.

Allowed are constant values, expressions and labels as content.
Constant values can be set as decimal, hexadecimal (with prefixed $), chars (surrounded by ' or ").
Labels are treated as 16-bit values. To get the high or low byte prefix the label with < (low byte) or > (high byte)
Expressions are evaluated during the final pass. They must evaluate to a valid byte value.



!byte 1,3,6,3,1 !byte <NoBehaviour !byte ( SCREEN_CHAR + 0 ) & 0x00ff


!CONVTAB, !CT <raw/scr/pet/mapping list>

This pseudo op allows sets a conversion table for text in !TEXT entries. You can pass either raw, scr or pet for inbuilt mapping, or provide a manual mapping list.

If RAW is set byte values are inserted as is. Any existing mapping list is cleared.

If SCR is set any byte values are mapped to screen codes. Any existing mapping list is cleared.

PET works like text but reverses character casing. Any existing mapping list is cleared.

A byte list is treated as a pair of bytes, first the original character, second the replacement byte. A mapping list can be split over several lines.

!text defaults to raw encoding.


!CONVTAB scr !text "HELLO WORLD" !CT 'A',17,'B',18,'C',19,'D',20,'E',21,'F',22,'G',23,'H',24,'I',25,'J',26,'K',27,'L',28,'M',29,'N',30,'O',31,'P',32,'Q',33,'R',34,'S',35,'T',36 !CT 'U',37,'V',38,'W',39,'X',40,'Y',41,'Z',42,'0',5,'1',6,'2',7,'3',8,'4',9,'5',10,'6',11,'7',12,'8',13,'9',14,'*',0,' ',16,'.',113 !text "HELLO WORLD AGAIN"


!CPU <cpu type>

This pseudo op sets the processor to assemble for. Currently there are four supported processors. Default is 6510.

* 6502 - 6502 without illegal opcodes
* 6510 - Default 6510 with illegal opcodes (used e.g. in C64)
* 65C02 - 6502 with BRA, PHX/Y, PLX/Y, STZ, TRB/TSB
* R65C02 - 65C02 with BBRx, BBSx, RMBx, SMBx
* W65C02 - WDC 65C02
* 65CE02
* 4502
* M65 - 4502 with long and quad mode using prefixes (used e.g. in Mega65)
* 65816 (also known as W65C816S or 65C816)
* Z80
* 68000



!cpu 6510


!DWORD, !32, !LE32, !BE32

This pseudo op allows to insert a double word (4 bytes) at the current location.

Allowed are constant values, expressions and labels as content.
Constant values can be set as decimal, hexadecimal (with prefixed $).
Labels are treated as 32-bit values. Default is little endian, unless !BE32 is used.
Expressions are evaluated during the final pass. They must evaluate to a valid word value.



!dword 128,270,320 !32 NoBehaviour !le32 ( SCREEN_CHAR + 40 )


!END

This pseudo op specifies the end of a !FOR or !MACRO function.


!ENDOFFILE, !EOF

This pseudo op ends the parsing of the file at the current line.


rts !endoffile This file is a carefully handcrafted demo


!ERROR, !SERIOUS <message>

This pseudo op adds an error message to the compile result, essentially breaking the build. The message can be any combination of strings and expressions. Expressions are evaluated where possible.

This pseudo op can be useful inside conditional pseudo op statements to do safety checking.



!error "File is ", CODE_END - CODE_START, " bytes long, longer than 2048 bytes!"


!FOR <Variable> = <Start Value Expression> TO <End Value Expression> [STEP <Step Value Expression>]

This pseudo op starts a for loop. To end a for loop specify !END
can be global or local (local starts with a dot)
Start value, end value and step value are treated as expressions.



!for ROW = 0 TO 24 lda BACK_BUFFER + ROW * 40 sta SCREEN_CHAR + ROW * 40 !end


!FILL, !FI <count>[,<value>]
!FILL, !FI <count>,[expression (list)]

This pseudo op fills the given value count times at the current location.
The expression form can be a list, several expressions are separated by comma. !fill uses every element of a list after each other, and restarts at the first element if required. The calculation is evaluated for every byte. The expression inside the brackets uses the label "i" as index, counting the usage of the full list. Any global "i" label is suspended inside the brackets and restored afterwards.

Example #1 - simple fill


!fill 8

Fills 8 bytes with value zero.

Example #2 - simple fill with value


!fill 8,$ff

Fills 8 bytes with value $ff.

Example #3 - fill with expression


!fill 5, [i * 3]

Fills 5 bytes, with values 0, 3, 6, 9, 12.

Example #4 - fill with list


!fill 4, [0,i]

Fills 4 * 2 bytes, with values 0, 0, 0, 1, 0, 2 0, 3.


!HEX, !H <hex data>

This pseudo op interprets the rest of the line as hex data, no commas or prefixes like $ or 0x. Data may be separated by spaces, but pairs need to be intact.



!hex f0 f1 f2 f3 !h f0f1f2f3


!IF, !IFDEF <expression> {

This pseudo op starts an conditional block. The conditional block is only evaluated if the expression yields a result not equal to zero. The opening curly brace must be on the same line.

!IF checks if the expression is not equal zero, !IFDEF only checks if the expression is defined at all.

A conditional block has to end with a closing curly brace. An optional else or else if statement may open an opposite conditional block, however it must be stated on one line.


!ifdef MUSIC_PLAYING{ ;initialise music player ldx #0 ldy #0 lda #MUSIC_TITLE_TUNE jsr MUSIC_PLAYER } else if SFX_PLAYING { ;start sfx engine lda #0 jsr SFX_PLAYER } else { lda #7 sta VIC_BORDER_COLOR }


!IFNDEF <expression> {

This pseudo op starts an conditional block. The conditional block is only evaluated if the expression yields a result of zero. The opening curly brace must be on the same line.

A conditional block has to end with a closing curly brace. An optional else or else if statement may open an opposite conditional block, however it must be stated on one line.


!ifndef COMPILE_CRUNCHED { CHARSET !binary "soulless1.chr" !binary "soulless2.chr" CHARSET_PANEL !binary "panel.chr" SPRITES !binary "soulless.spr" } else if COMPILE_FOR_TAPE { lda #1 sta AUTO_LOAD } else { lda #0 sta AUTO_LOAD }


!LIST <on/off>

This pseudo op allows to suppress output in preprocessed files. Use !list on to turn on, and !list off to turn off.



!list off


!LZONE <zone/label name>

This pseudo op declares a new zone plus a global label with the same name. Any local labels (labels starting with '.') are only accessible inside their containing zone.



!lzone MainZone .locallabel ... !zone SubZone .locallabel


!MACRO <Function Name> [<Parameter 1>[,<Parameter 2>],..]

This pseudo op defines a macro function. To end the body of a function specify !END
The number of parameters is variable. Optionally a !macro definition may also be encapsulated by {, } curly braces.

To call a macro use +<Function Name> [<Parameter 1>[,<Parameter 2>],..]



!macro fill5bytes v1,v2,v3,v4,v5 lda #v1 sta 1024 lda #v2 sta 1025 lda #v3 sta 1026 lda #v4 sta 1027 lda #v5 sta 1028 !end !macro fill3bytes v1,v2,v3 { lda #v1 sta 1064 lda #v2 sta 1065 lda #v3 sta 1066 } lda #$01 sta $d021 +fill5bytes 10,20,30,40,50 +fill3bytes 17,18,19 inc $d020


!MEDIA <File name>,<Method>[,<Method Parameters>...]

This pseudo op allows to directly include relevant portions of different binary or project files. Currently the pseudo op supports character files (*.chr), character project files (*.charsetproject), sprite files (*.spr), sprite project files( *.spriteproject), character screen project files (*.charsetscreen), graphic screen project files (*.graphicscreen) and map project files (*.mapproject).
Method defines what and in which order to export data. The method depends on the given file.

Method Parameters are optional and determine a subset of the export data as applicable.


File Format Extension Method Method Parameters Export
Character File *.chr char None Exports all characters data bytes of the source file (C64 256 * 8, FCM 256 * 64, FCM 16bit 8192 * 64)
Character File *.chr char Index, Count Exports Count character data bytes starting at Index of the source file
Character Project File *.charsetproject char None Exports all characters data bytes of the source file (C64 256 * 8, FCM 256 * 64, FCM 16bit 8192 * 64)
Character Project File *.charsetproject char Index, Count Exports Count character data bytes starting at Index bytes of the character data
Character Project File *.charsetproject palette None Exports all colors from all palettes, color values ordered all reds, then all greens, then all blues
Character Project File *.charsetproject palette Index, Count Exports count colors, starting at index, over all palettes, color values ordered all reds, then all greens, then all blues
Character Project File *.charsetproject palettergb None Exports all colors from all palettes, color values ordered as RGB triplets
Character Project File *.charsetproject palettergb Index, Count Exports count colors, starting at index, over all palettes, color values ordered as RGB triplets
Character Project File *.charsetproject paletteswizzled None Exports all colors from all palettes, color values ordered all reds, then all greens, then all blues. Color bytes are swizzled (nibbles swapped) Used for Mega65
Character Project File *.charsetproject paletteswizzled Index, Count Exports count colors, starting at index, over all palettes, color values ordered all reds, then all greens, then all blues. Color bytes are swizzled (nibbles swapped) Used for Mega65
Character Project File *.charsetproject palettergbswizzled None Exports all colors from all palettes, color values ordered as RGB triplets. Color bytes are swizzled (nibbles swapped)
Character Project File *.charsetproject palettergbswizzled Index, Count Exports count colors, starting at index, over all palettes, color values ordered as RGB triplets. Color bytes are swizzled (nibbles swapped)
Sprite File *.spr sprite spriteoptimize None Exports all sprite data bytes of the source file (C64 256 * 64, Mega65 Expanded 256 * 168, NCM 256 * 168). If optimize is not set sprite data is padded (C64 aligns sprites to 64 bytes, Mega65 aligns sprites to 192 bytes)
Sprite File *.spr sprite spriteoptimize Index, Count Exports Count sprite data bytes starting at Index bytes of the source file If optimize is not set sprite data is padded (C64 aligns sprites to 64 bytes, Mega65 aligns sprites to 192 bytes)
Sprite File *.spr spritedata spritedataoptimize Index, Count, Offset, Number of Bytes Takes the sprite data for Count sprites starting at Index and exports Number of Bytes bytes starting at Offset from there If optimize is not set sprite data is padded (C64 aligns sprites to 64 bytes, Mega65 aligns sprites to 192 bytes)
Sprite Project File *.spriteproject sprite spriteoptimize None Exports all sprite data bytes of the source file (C64 256 * 64, Mega65 Expanded 256 * 168, NCM 256 * 168) If optimize is not set sprite data is padded (C64 aligns sprites to 64 bytes, Mega65 aligns sprites to 192 bytes)
Sprite Project File *.spriteproject sprite spriteoptimize Index, Count Exports Count sprite data bytes starting at Index bytes of the sprite data If optimize is not set sprite data is padded (C64 aligns sprites to 64 bytes, Mega65 aligns sprites to 192 bytes)
Sprite Project File *.spriteproject spritedata spritedataoptimize Index, Count, Offset, Number of Bytes Takes the sprite data for Count sprites starting at Index and exports Number of Bytes bytes starting at Offset from there If optimize is not set sprite data is padded (C64 aligns sprites to 64 bytes, Mega65 aligns sprites to 192 bytes)
Sprite Project File *.spriteproject palette None Exports all colors from all palettes, color values ordered all reds, then all greens, then all blues
Sprite Project File *.spriteproject palette Index, Count Exports count colors, starting at index, over all palettes, color values ordered all reds, then all greens, then all blues
Sprite Project File *.spriteproject palettergb None Exports all colors from all palettes, color values ordered as RGB triplets
Sprite Project File *.spriteproject palettergb Index, Count Exports count colors, starting at index, over all palettes, color values ordered as RGB triplets
Sprite Project File *.spriteproject paletteswizzled None Exports all colors from all palettes, color values ordered all reds, then all greens, then all blues. Color bytes are swizzled (nibbles swapped)
Sprite Project File *.spriteproject paletteswizzled Index, Count Exports count colors, starting at index, over all palettes, color values ordered all reds, then all greens, then all blues. Color bytes are swizzled (nibbles swapped)
Sprite Project File *.spriteproject palettergbswizzled None Exports all colors from all palettes, color values ordered as RGB triplets. Color bytes are swizzled (nibbles swapped)
Sprite Project File *.spriteproject palettergbswizzled Index, Count Exports count colors, starting at index, over all palettes, color values ordered as RGB triplets. Color bytes are swizzled (nibbles swapped)
Spritepad Project File *.spd sprite None Exports 256 * 64 bytes of the sprite data
Spritepad Project File *.spd sprite Index, Count Exports Count * 64 bytes starting at Index * 64 bytes of the sprite data
Spritepad Project File *.spd spritedata Index, Count, Offset, Number of Bytes Takes the sprite data for Count sprites starting at Index (*64) and exports Number of Bytes bytes starting at Offset from there
Character Screen Project File *.charscreen char None Exports 40 * 25 bytes of the screen character data
Character Screen Project File *.charscreen charvert None Exports 40 * 25 bytes of the screen character data, column major
Character Screen Project File *.charscreen char x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen character data
Character Screen Project File *.charscreen charvert x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen character data, column major
Character Screen Project File *.charscreen color None Exports 40 * 25 bytes of the screen color data
Character Screen Project File *.charscreen colorvert None Exports 40 * 25 bytes of the screen color data, column major
Character Screen Project File *.charscreen color x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen color data
Character Screen Project File *.charscreen colorvert x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen color data, column major
Character Screen Project File *.charscreen charcolor None Exports 40 * 25 bytes of the screen char data
followed by 40 * 25 bytes of the screen color data
Character Screen Project File *.charscreen charcolorvert None Exports 40 * 25 bytes of the screen char data
followed by 40 * 25 bytes of the screen color data
Both column major
Character Screen Project File *.charscreen charcolor x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen char data
followed by width * height bytes starting at screen coordinates x,y of the screen color data
Character Screen Project File *.charscreen charcolorvert x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen char data
followed by width * height bytes starting at screen coordinates x,y of the screen color data
Both column major
Character Screen Project File *.charscreen colorchar None Exports 40 * 25 bytes of the screen color data
followed by 40 * 25 bytes of the screen char data
Character Screen Project File *.charscreen colorcharvert None Exports 40 * 25 bytes of the screen color data
followed by 40 * 25 bytes of the screen char data
Both column major
Character Screen Project File *.charscreen colorchar x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen color data
followed by width * height bytes starting at screen coordinates x,y of the screen char data
Character Screen Project File *.charscreen colorcharvert x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen color data
followed by width * height bytes starting at screen coordinates x,y of the screen char data
Both column major
Character Screen Project File *.charscreen charset None Exports the data of all characters in the charset
Character Screen Project File *.charscreen charset Index, Count Exports Count * 8 bytes starting at Index * 8 bytes of the character data
Character Screen Project File *.charscreen palette None Exports all colors from all palettes, color values ordered all reds, then all greens, then all blues
Character Screen Project File *.charscreen palette Index, Count Exports count colors, starting at index, over all palettes, color values ordered all reds, then all greens, then all blues
Character Screen Project File *.charscreen palettergb None Exports all colors from all palettes, color values ordered as RGB triplets
Character Screen Project File *.charscreen palettergb Index, Count Exports count colors, starting at index, over all palettes, color values ordered as RGB triplets
Character Screen Project File *.charscreen paletteswizzled None Exports all colors from all palettes, color values ordered all reds, then all greens, then all blues. Color bytes are swizzled (nibbles swapped)
Character Screen Project File *.charscreen paletteswizzled Index, Count Exports count colors, starting at index, over all palettes, color values ordered all reds, then all greens, then all blues. Color bytes are swizzled (nibbles swapped)
Character Screen Project File *.charscreen palettergbswizzled None Exports all colors from all palettes, color values ordered as RGB triplets. Color bytes are swizzled (nibbles swapped)
Character Screen Project File *.charscreen palettergbswizzled Index, Count Exports count colors, starting at index, over all palettes, color values ordered as RGB triplets. Color bytes are swizzled (nibbles swapped)
Graphic Screen Project File *.graphicscreen bitmap None Exports 8 * 40 * 25 (8000) bytes of the bitmap data
Graphic Screen Project File *.graphicscreen bitmap x,y,width,height Exports 8 * width * height bytes starting at screen coordinates x,y of the bitmap data
x,y, width and height must be multiples of 8
Graphic Screen Project File *.graphicscreen bitmaphires None Exports 8 * 40 * 25 (8000) bytes of the bitmap data interpreted as hires
Graphic Screen Project File *.graphicscreen bitmaphires x,y,width,height Exports 8 * width * height bytes starting at screen coordinates x,y of the bitmap data interpreted as hires
x,y, width and height must be multiples of 8
Graphic Screen Project File *.graphicscreen screen None Exports 40 * 25 (1000) bytes of the screen data
Graphic Screen Project File *.graphicscreen screen x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen data
x,y, width and height must be multiples of 8
Graphic Screen Project File *.graphicscreen color None Exports 40 * 25 (1000) bytes of the color data
Graphic Screen Project File *.graphicscreen color x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the color data
x,y, width and height must be multiples of 8
Graphic Screen Project File *.graphicscreen bitmapscreen None Exports 8 * 40 * 25 (8000) bytes of the bitmap data
followed by 40 * 25 (1000) bytes of the screen data
Graphic Screen Project File *.graphicscreen bitmaphiresscreen None Exports 8 * 40 * 25 (8000) bytes of the bitmap data interpreted as hires
followed by 40 * 25 (1000) bytes of the screen data
Graphic Screen Project File *.graphicscreen bitmapscreen x,y,width,height Exports 8 * width * height bytes starting at screen coordinates x,y of the bitmap data
followed by width * height bytes starting at screen coordinates x,y of the screen data
x,y, width and height must be multiples of 8
Graphic Screen Project File *.graphicscreen bitmaphiresscreen x,y,width,height Exports 8 * width * height bytes starting at screen coordinates x,y of the bitmap data interpreted as hires
followed by width * height bytes starting at screen coordinates x,y of the screen data
x,y, width and height must be multiples of 8
Graphic Screen Project File *.graphicscreen bitmapscreencolor None Exports 8 * 40 * 25 (8000) bytes of the bitmap data
followed by 40 * 25 (1000) bytes of the screen data
followed by 40 * 25 (1000) bytes of the color data
Graphic Screen Project File *.graphicscreen bitmaphiresscreencolor None Exports 8 * 40 * 25 (8000) bytes of the bitmap data interpreted as hires
followed by 40 * 25 (1000) bytes of the screen data
followed by 40 * 25 (1000) bytes of the color data
Graphic Screen Project File *.graphicscreen bitmapscreencolor x,y,width,height Exports 8 * width * height bytes starting at screen coordinates x,y of the bitmap data
followed by width * height bytes starting at screen coordinates x,y of the screen data
followed by width * height bytes starting at screen coordinates x,y of the color data
x,y, width and height must be multiples of 8
Graphic Screen Project File *.graphicscreen bitmaphiresscreencolor x,y,width,height Exports 8 * width * height bytes starting at screen coordinates x,y of the bitmap data interpreted as hires
followed by width * height bytes starting at screen coordinates x,y of the screen data
followed by width * height bytes starting at screen coordinates x,y of the color data
x,y, width and height must be multiples of 8
Value Table Project File *.valuetableproject data None Exports all values as single bytes. Values are capped to the range 0 to 255
Value Table Project File *.valuetableproject data Index, Count Exports Count values starting with Index as single bytes. Values are capped to the range 0 to 255
Map Project File *.mapproject char None Exports all characters data bytes of the source file (C64 256 * 8, FCM 256 * 64, FCM 16bit 8192 * 64)
Map Project File *.mapproject char Index, Count Exports Count character data bytes starting at Index bytes of the character data




;character sets !media "panel.chr",char !media "panel.chr",char,10,32 !media "panel.charsetproject",char !media "panel.charsetproject",char,10,32 !media "stage1.mapproject",char !media "stage1.mapproject",char,0,200 ;sprites !media "enemies.spr",sprite !media "enemies.spr",sprite,10,96 !media "enemies.spriteproject",sprite !media "enemies.spriteproject",sprite,10,96 ;text screen !media "title.charscreen",char !media "title.charscreen",char,10,10,20,5 !media "title.charscreen",color !media "title.charscreen",color,10,10,20,5 !media "title.charscreen",charcolor !media "title.charscreen",charcolor,10,10,20,5 !media "title.charscreen",colorchar !media "title.charscreen",colorchar,10,10,20,5 ;Bitmap !media "intro.graphicscreen",bitmap !media "intro.graphicscreen",bitmap,8,8,304,184 !media "intro.graphicscreen",screen !media "intro.graphicscreen",screen,8,8,304,184 !media "intro.graphicscreen",color !media "intro.graphicscreen",color,8,8,304,184 !media "intro.graphicscreen",bitmapscreen !media "intro.graphicscreen",bitmapscreen,8,8,304,184 !media "intro.graphicscreen",bitmapscreencolor !media "intro.graphicscreen",bitmapscreencolor,8,8,304,184


!MEDIASRC <File name>,<LabelPrefix>,<Method>[,<Method Parameters>...]

This pseudo op allows to include relevant portions of project files as assembly. Currently the pseudo op supports character screen project files (*.charsetscreen), graphic screen project files (*.graphicscreen) and map project files (*.mapproject).
LabelPrefix is prefixed to all generated labels. This allows to reference assembled parts directly.

Method defines what and in which order to export data. The method depends on the given file.

Method Parameters are optional and determine a subset of the export data as applicable.


File Format Extension Method Method Parameters Export
Character Screen Project File *.charscreen char None Exports 40 * 25 bytes of the screen character data as assembly directive.
A label named <LabelPrefix>_CHARS is inserted before the binary data.
Character Screen Project File *.charscreen char x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen character data as assembly directive.
A label named <LabelPrefix>_CHARS is inserted before the binary data.
Character Screen Project File *.charscreen color None Exports 40 * 25 bytes of the screen color data as assembly directive.
A label named <LabelPrefix>_COLOR is inserted before the binary data.
Character Screen Project File *.charscreen color x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen color data as assembly directive.
A label named <LabelPrefix>_COLOR is inserted before the binary data.
Character Screen Project File *.charscreen charcolor None Exports 40 * 25 bytes of the screen char data as assembly directive.
followed by 40 * 25 bytes of the screen color data as assembly directive.
A label named <LabelPrefix>_CHARS is inserted before the screen char data.
A label named <LabelPrefix>_COLOR is inserted before the screen color data.
Character Screen Project File *.charscreen color x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen char data as assembly directive.
followed by width * height bytes starting at screen coordinates x,y of the screen color data as assembly directive.
A label named <LabelPrefix>_CHARS is inserted before the screen char data.
A label named <LabelPrefix>_COLOR is inserted before the screen color data.
Character Screen Project File *.charscreen colorchar None Exports 40 * 25 bytes of the screen color data as assembly directive.
followed by 40 * 25 bytes of the screen char data as assembly directive.
A label named <LabelPrefix>_CHARS is inserted before the screen char data.
A label named <LabelPrefix>_COLOR is inserted before the screen color data.
Character Screen Project File *.charscreen colorchar x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen color data as assembly directive.
followed by width * height bytes starting at screen coordinates x,y of the screen char data as assembly directive.
A label named <LabelPrefix>_CHARS is inserted before the screen char data.
A label named <LabelPrefix>_COLOR is inserted before the screen color data.
Graphic Screen Project File *.graphicscreen bitmap None Exports 8 * 40 * 25 (8000) bytes of the bitmap data as assembly directive.
A label named <LabelPrefix>_BITMAP_DATA is inserted before the bitmap data.
Graphic Screen Project File *.graphicscreen bitmap x,y,width,height Exports 8 * width * height bytes starting at screen coordinates x,y of the bitmap data as assembly directive.
A label named <LabelPrefix>_BITMAP_DATA is inserted before the bitmap data.
x,y, width and height must be multiples of 8
Graphic Screen Project File *.graphicscreen screen None Exports 40 * 25 (1000) bytes of the screen data as assembly directive.
A label named <LabelPrefix>_SCREEN_DATA is inserted before the screen data.
Graphic Screen Project File *.graphicscreen screen x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the screen data as assembly directive.
A label named <LabelPrefix>_SCREEN_DATA is inserted before the screen data.
x,y, width and height must be multiples of 8
Graphic Screen Project File *.graphicscreen color None Exports 40 * 25 (1000) bytes of the color data as assembly directive.
A label named <LabelPrefix>_COLOR_DATA is inserted before the screen data.
Graphic Screen Project File *.graphicscreen color x,y,width,height Exports width * height bytes starting at screen coordinates x,y of the color data as assembly directive.
A label named <LabelPrefix>_COLOR_DATA is inserted before the screen data.
x,y, width and height must be multiples of 8
Graphic Screen Project File *.graphicscreen bitmapscreen None Exports 8 * 40 * 25 (8000) bytes of the bitmap data as assembly directive.
followed by 40 * 25 (1000) bytes of the screen data as assembly directive.
A label named <LabelPrefix>_BITMAP_DATA is inserted before the bitmap data.
A label named <LabelPrefix>_SCREEN_DATA is inserted before the screen data.
Graphic Screen Project File *.graphicscreen bitmapscreen x,y,width,height Exports 8 * width * height bytes starting at screen coordinates x,y of the bitmap data as assembly directive.
followed by width * height bytes starting at screen coordinates x,y of the screen data as assembly directive.
A label named <LabelPrefix>_BITMAP_DATA is inserted before the bitmap data.
A label named <LabelPrefix>_SCREEN_DATA is inserted before the screen data.
x,y, width and height must be multiples of 8
Graphic Screen Project File *.graphicscreen bitmapscreencolor None Exports 8 * 40 * 25 (8000) bytes of the bitmap data as assembly directive.
followed by 40 * 25 (1000) bytes of the screen data as assembly directive.
followed by 40 * 25 (1000) bytes of the color data as assembly directive.
A label named <LabelPrefix>_BITMAP_DATA is inserted before the bitmap data.
A label named <LabelPrefix>_SCREEN_DATA is inserted before the screen data.
A label named <LabelPrefix>_COLOR_DATA is inserted before the screen data.
Graphic Screen Project File *.graphicscreen bitmapscreencolor x,y,width,height Exports 8 * width * height bytes starting at screen coordinates x,y of the bitmap data as assembly directive.
followed by width * height bytes starting at screen coordinates x,y of the screen data as assembly directive.
followed by width * height bytes starting at screen coordinates x,y of the color data as assembly directive.
A label named <LabelPrefix>_BITMAP_DATA is inserted before the bitmap data.
A label named <LabelPrefix>_SCREEN_DATA is inserted before the screen data.
A label named <LabelPrefix>_COLOR_DATA is inserted before the screen data.
x,y, width and height must be multiples of 8
Map Project File *.mapproject tileelements None Exports all tiles as arbitrary sized elements like this:
<LabelPrefix>NUM_TILES = (number of tiles)
Label <LabelPrefix>TILE_WIDTH (all tile widths)
Label <LabelPrefix>TILE_HEIGHT (all tile heights)
Label <LabelPrefix>TILE_CHARS_LO (low byte of pointer to tile char list)
Label <LabelPrefix>TILE_CHARS_HI (high byte of pointer to tile char list)
Label <LabelPrefix>TILE_COLORS_LO (low byte of pointer to tile color list)
Label <LabelPrefix>TILE_COLORS_HI (high byte of pointer to tile color list)
Label <LabelPrefix>TILE_CHAR_(tile name) (tile chars of tile)
Label <LabelPrefix>TILE_COLOR_(tile name) (tile chars of tile)
Map Project File *.mapproject tiledata None Exports all tiles as two byte blocks (char/colors) like this:
Label <LabelPrefix>_<TileIndex>_CHARS (characters of tile)
Label <LabelPrefix>_<TileIndex>_COLORS (colors of tile)
Map Project File *.mapproject tile None Exports all tiles as lookup tables like this:
<LabelPrefix>NUM_TILES = (number of tiles)
Label <LabelPrefix>TILE_CHARS_<0..max width - 1>_<0..max height - 1> (all tiles chars at x, y)
Label <LabelPrefix>TILE_COLORS_<0..max width - 1>_<0..max height - 1> (all tiles colors at x, y)
Map Project File *.mapproject map None Exports all maps as lookup tables like this:
<LabelPrefix>NUM_MAPS = (number of maps)
<LabelPrefix>MAP_LIST_LO (low bytes of pointer to map data)
<LabelPrefix>MAP_LIST_HI (high bytes of pointer to map data)
Only if at least one map has valid extra data:
<LabelPrefix>MAP_EXTRA_DATA_LIST_LO (low bytes of pointer to map extra data)
<LabelPrefix>MAP_EXTRA_DATA_LIST_HI (high bytes of pointer to map extra data)
For every map:
<LabelPrefix>MAP_<map name> (all tile indices of a map)
(all extra data bytes of a map)
Map Project File *.mapproject mapvertical None Exports all maps as lookup tables like this:
<LabelPrefix>NUM_MAPS = (number of maps)
<LabelPrefix>MAP_LIST_LO (low bytes of pointer to map data)
<LabelPrefix>MAP_LIST_HI (high bytes of pointer to map data)
Only if at least one map has valid extra data:
<LabelPrefix>MAP_EXTRA_DATA_LIST_LO (low bytes of pointer to map extra data)
<LabelPrefix>MAP_EXTRA_DATA_LIST_HI (high bytes of pointer to map extra data)
For every map:
<LabelPrefix>MAP_<map name> (all tile indices of a map column major)
(all extra data bytes of a map)
Map Project File *.mapproject mapextradata None Exports all map extradata as lookup tables like this:
<LabelPrefix>NUM_MAPS = (number of maps)
Only if at least one map has valid extra data:
<LabelPrefix>MAP_EXTRA_DATA_LIST_LO (low bytes of pointer to map extra data)
<LabelPrefix>MAP_EXTRA_DATA_LIST_HI (high bytes of pointer to map extra data)
For every map:
<LabelPrefix>MAP_<map name> (all tile indices of a map column major)
(all extra data bytes of a map)
Map Project File *.mapproject maptile None Exports all tiles and maps. Simply concatenates the output of "tile" and "mapvertical"
Map Project File *.mapproject mapverticaltile None Exports all tiles and maps. Simply concatenates the output of "tile" and "mapvertical"




;text screen !mediasrc "title.charscreen",char !mediasrc "title.charscreen",char,10,10,20,5 !mediasrc "title.charscreen",color !mediasrc "title.charscreen",color,10,10,20,5 !mediasrc "title.charscreen",charcolor !mediasrc "title.charscreen",charcolor,10,10,20,5 !mediasrc "title.charscreen",colorchar !mediasrc "title.charscreen",colorchar,10,10,20,5 ;Bitmap !mediasrc "intro.graphicscreen",bitmap !mediasrc "intro.graphicscreen",bitmap,8,8,304,184 !mediasrc "intro.graphicscreen",screen !mediasrc "intro.graphicscreen",screen,8,8,304,184 !mediasrc "intro.graphicscreen",color !mediasrc "intro.graphicscreen",color,8,8,304,184 !mediasrc "intro.graphicscreen",bitmapscreen !mediasrc "intro.graphicscreen",bitmapscreen,8,8,304,184 !mediasrc "intro.graphicscreen",bitmapscreencolor !mediasrc "intro.graphicscreen",bitmapscreencolor,8,8,304,184 ;Maps !mediasrc "overworld.map",tileelements !mediasrc "overworld.map",tile !mediasrc "overworld.map",map !mediasrc "overworld.map",tilemap


!MESSAGE <message>

This pseudo op adds a message to the output. The message can be any combination of strings and expressions. Expressions are evaluated where possible.

This pseudo op can be useful to output compile time evaluated values (e.g. size of a code section).



!message "The compiled section is ", CODE_END - CODE_START, " bytes long"


!NOWARN <warning code(s)>

This pseudo op temporarily adds the given warnings to the ignore warning list.

The warning codes are expected in the Wxxxx form. To ignore the overlapping segment warning (W0001) call like shown in the sample below.



!NOWARN w0001


!PSEUDOPC <address>

This pseudo op alters the following assembly as if the current memory location was starting with the provided address.

Allowed are constant values, expressions and labels as content. Mainly useful for code that will be copied around or bank switched (cartridge). When setting !REALPC the program counter is set to the proper location address again.



!PSEUDOPC $0400 ... !REALPC


!REALIGN <alignaddress>[,<fillvalue>]

This pseudo op fills memory until a full multiple of alignaddress is reached.
If [fillvalue] is omitted 0 is used.



!realign $2 ;wait for even address !realign 256 ;align code to page border


!REALPC

This pseudo op is the counter part for !PSEUDOPC. The following assembly is used the proper memory location.

When setting !REALPC the program counter is set to the proper location address again after a !PSEUDOPC.



!PSEUDOPC $0400 ... !REALPC


!TO <file name>,<output type>

This pseudo op sets the output file name and type. This pseudo op will be overridden by any valid output settings in the element properties.


Valid output types are CBM, PLAIN, D64, T64, TAP, CART8BIN, CART8CRT, CART16BIN, CART16CRT, MAGICDESKBIN, MAGICDESKCRT, MAGICDESK32BIN, MAGICDESK32CRT, MAGICDESK128BIN, MAGICDESK128CRT, MAGICDESK256BIN, MAGICDESK256CRT, MAGICDESK512BIN, MAGICDESK512CRT, MAGICDESK1MBIN, MAGICDESK1MCRT, EASYFLASHBIN, EASYFLASHCRT, RGCDBIN, RGCDCRT, GMOD2BIN, GMOD2CRT, ULTIMAX4BIN, ULTIMAX4CRT, ULTIMAX8BIN, ULTIMAX8CRT, ULTIMAX16BIN, ULTIMAX16CRT

For cartridge and tape/disk formats a dummy name is currently inserted in the final file.



!to "jmain.prg",cbm !to "cart64banks.crt.bin", magicdeskcrt


!SCRXOR <xor value>,...

This pseudo op works exactly like !scr, but allows to specify an expression which is used to XOR the following bytes.



!scrxor $55, "HELLO WORLD"


!SET <label> = <expression>

This pseudo op assigns a value or result of an expression to a label. Exactly the same like direct assignment, but an existing label can be reassigned with a different value.



!set SCREEN_CHAR = $0400


!SKIP <expression>

This pseudo op skips over a given number of bytes, it works similar to * = * + <expression>



!skip 5 * 20 ;skip 100 bytes forwards


!SL <file name>

This pseudo op instructs the assembler to write a text file with all labels to the given filename.
The file is a csv formatted text file, with no header and semicolon as separator.
There are two columns:
[Labelname]=$[Value];[Unused]

When the label is not used the content of the second column is set to "unused"



!sl "labels.txt"


!SOURCE <file name>

This pseudo op includes another source file at the current location. File names are used relative to the file containing the directive.

If the file name is given in <,> the file is searched for in the configured library paths.



!source "tiles.asm" !source <kernal.asm>


!TEXT, !TX, !SCR, !PET, !RAW

This pseudo op allows to insert text, characters, or one ore more bytes at the current location.
Text literals allow the inclusion of text symbols in squiggly braces. See here for a list. For any macro the PETSCII value is used always, independent from the current used mapping.

Allowed are text literals, character literals, constant values, expressions and labels as content.
text literals are surrounded by ", character literals by '
Constant values can be set as decimal, hexadecimal (with prefixed $), chars (surrounded by ' or ").
Labels are treated as 16-bit values. To get the high or low byte prefix the label with < (low byte) or > (high byte)
Expressions are evaluated during the final pass. They must evaluate to a valid byte value.
Any values are subject to being mapped to the currently set conversation table.
!SCR will insert screen codes, while !PET works like !TEXT, but reverses character casing. !RAW inserts bytes untouched.

!text defaults to raw encoding.



!text "HELLO WORLD" !text " SCORE",60," 00000000 ",224,224," LEVEL",60," 00 ",225,225," LIVES",60," 03 *" !text 206,184,191,182,198,196,184,0,203,198,0,202,198,204,191,191,184,202,202,0,0 !text "{clr}HELLO WORLD"


!TO <file name>,<output type>

This pseudo op sets the output file name and type. This pseudo op will be overridden by any valid output settings in the element properties.


Valid output types are CBM, PLAIN, D64, T64, TAP, CART8BIN, CART8CRT, CART16BIN, CART16CRT, MAGICDESKBIN, MAGICDESKCRT, EASYFLASHBIN, EASYFLASHCRT, RGCDBIN, RGCDCRT, GMOD2BIN, GMOD2CRT, ULTIMAX4BIN, ULTIMAX4CRT, ULTIMAX8BIN, ULTIMAX8CRT, ULTIMAX16BIN, ULTIMAX16CRT

For cartridge and tape/disk formats a dummy name is currently inserted in the final file.



!to "jmain.prg",cbm !to "cart64banks.crt.bin", magicdeskcrt


!TRACE <Expression>

This pseudo op allows the tracing of a memory location. The expression is evaluated anew on every pass at this location. The resulting value is treated as address and the byte fetched from the current visible RAM/ROM. The value is written to the output window.

This pseudo op will only be processed if the debugger is started, not on normal runs. Note that this pseudo op will cause major slowdowns during debugging.




!trace VIC_RASTER_POS


!WARN <message>

This pseudo op adds a warning message to the compile result. The message can be any combination of strings and expressions. Expressions are evaluated where possible.



!warning "File is ", CODE_END - CODE_START, " bytes long, longer than 2048 bytes!"


!WHILE<Expression> {

This pseudo op starts a while loop. The expression must be true for the loop to continue. C64Studio automatically aborts assembling if the loop is run over 1000 times.


a = 5 !while a > 0 { lda #a sta SCREEN_CHAR + a a = a - 1 }


!WORD, !WO, !16, !LE16, !BE16

This pseudo op allows to insert words (2 bytes) at the current location.

Allowed are constant values, expressions and labels as content.
Constant values can be set as decimal, hexadecimal (with prefixed $).
Labels are treated as 16-bit values. Default is little endian, unless !BE16 is used.
Expressions are evaluated during the final pass. They must evaluate to a valid word value.



!word 128,270,320 !word NoBehaviour !word ( SCREEN_CHAR + 40 )


!ZONE <zone name>

This pseudo op declares a new zone. Any local labels (labels starting with '.') are only accessible inside their containing zone.



!zone MainZone .locallabel ... !zone SubZone .locallabel