Assembler - Macros
These macros are supported:
- !TO
- !SOURCE
- !BINARY, !BIN, !BI
- !BYTE, !BY, !8, !08
- !WORD, !WO, !16
- !FILL, !FI
- !ALIGN
- !TEXT, !TX, !SCR
- !CONVTAB, !CT
- !PSEUDOPC
- !REALPC
- !BANK
- !ZONE, !ZN
- !ERROR
- !IFDEF, !IF
- !IFNDEF
- !ENDOFFILE
- !FOR
- !MACRO
- !END
!TO [file name],[output type]
This macro includes overrides any build target settings given in the element properties. The output file name and type of the current file are determined.
Valid output types are CBM, PLAIN, CART8BIN, CART8CRT, CART16BIN, CART16CRT, MAGICDESKBIN, MAGICDESKCRT, D64, T64
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
!SOURCE [file name]
This macro includes another source file at the current location.
!source "tiles.asm"
!BINARY, !BIN, !BI [file name]<,[size]>,<[skip]>"
This macro 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 macro 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 $lt; (low byte) or $gt; (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
!WORD, !WO, !16
This macro 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.
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 )
!FILL, !FI [count],[value]
This macro fills the given value count times at the current location.
!fill 8,$ff
!fill ITEM_COUNT,0
!ALIGN andvalue,equalvalue[,fillvalue]
This macro 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
!TEXT, !TX, !SCR
This macro allows to insert text, characters, or one ore more bytes at the current location.
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 $lt; (low byte) or $gt; (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 current set conversation table.
!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
!CONVTAB, !CT [raw/scr/mapping list]
This macro allows sets a conversion table for text in !TEXT entries. You can pass either
raw or
scr 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.
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.
!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"
!PSEUDOPC [address]
This macro 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
!REALPC
This macro 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
!BANK [bank index],[bank size]
This macro 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 macro is encountered.
Usually !BANK will be used in conjunction with a !PSEUDOPC.
!bank 0,$2000
!ZONE [zone name]
This macro declares a new zone. Any local labels (labels starting with '.') are only accessible inside their containing zone.
!zone MainZone
.locallabel
...
!zone SubZone
.locallabel
!ERROR [message]
This macro adds an error message to the output, essentially breaking the build.
This macro can be useful inside conditional macro statements to do safety checking.
!error File too long
!IF, !IFDEF [expression] {
This macro 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.
A conditional block has to end with a closing curly brace. An optional else 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 {
;start sfx engine
lda #0
jsr SFX_PLAYER
}
!IFNDEF [expression] {
This macro 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 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 {
;start sfx engine
lda #0
jsr SFX_PLAYER
}
!ENDOFFILE
This macro ends the parsing of the file at the current line.
rts
!endoffile
This file is a carefully handcrafted demo
!FOR [Variable] = [Start Value Expression] TO [End Value Expression] [[STEP] [Step Value Expression]]
This macro 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
!MACRO [Function Name] [[Parameter 1],[[Parameter 2],..]]
This macro defines a function. To end the body of a function specify !END
The number of parameters is variable.
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
lda #$01
sta $d021
+fill5bytes 10,20,30,40,50
inc $d020
!END
This macro specifies the end of a !FOR or !MACRO function.